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Introduction 


Elasticsearch Java API 手册 








elasticsearch 
Java 手册 





本 手册 由 全 科 翻译 ， 并 且 整 理 成 电子 书 ， 支 持 PDFePub,Mobi 格 式 ， 方 便 大 家 下 
载 阅读 。 


阅读 地 址 : http://woquanke.com/books/esjava/ 

下 载 地 址 : https://www.gitbook.com/book/quanke/elasticsearch-java 
github 地 址 : https://github.com/quanke/elasticsearch-java 

gitee 地 址 : https://gitee.com/quanke/elasticsearch-java 


配套 示例 代码 : https://gitee.com/quanke/elasticsearch-java-study 


编辑 : http://woquanke.com 
编辑 整理 辛苦 ， 还 望 大 神 们 点 一 下 star ， 抚 平 我 虚荣 的 心 


不 只 是 官方 文档 的 翻译 ， 还 包含 使 用 实例 ， 包 人 钨 我 们 使 用 踩 过 的 坑 


~ ak Y ` 
推荐 阅读 
Elasticsearch Java Rest 手册 已 经 完成 大 部 分 


更 多 请 关注 我 的 微 信 公众 号 : 





下 面 几 个 章节 应 用 的 相对 少 ， 所 以 会 延 后 更 新 ， 计 划 先 把 配套 实例 elasticsearch- 
java-study 项 目 写 完 ; 


e Indexed Scripts API 
o Script Language 

e Java API Administration 
o Indices Administration 
o Cluster Administration 


e elasticsearch java API 官方 文档 
e elasticsearch 性 能 调 优 

e ElasticSearch 5.0.1 java API 操 作 
e fendo Elasticsearch £ H 

e Java API 之 滚动 搜索 (Scroll API) 


Introduction 


e Elastic Elasticsearch - ApacheCN (Apache? x: M 
e aggregation 详解 2 (metrics aggregations ) 

e aggregation 详解 3 (bucket aggregation ) 

e Percentile Ranks Aggregation 

e Java APIZ TermQuery 


安装 


Maven Repository 


Elasticsearch Java API 包 已 经 上 传 到 Maven Central 
在 pom.xml 文件 中 增加 : 


transport 版 本 号 最 好 就 是 与 Elasticsearch 版 本 号 一 致 。 


<dependency> 
<groupId>org.elasticsearch.client</groupId> 
<artifactId>transport</artifactId> 
<version>5.6.3</version> 

</dependency> 


Client 


Client 


Java 客户 端 连接 Elasticsearch 


一 个 是 TransportClient ， 一 个 是 NodeClient ， 还 有 一 


个 XPackTransportClient 
e TransportClient : 
作为 一 个 外 部 访问 者 ， 请 求 ES 的 集群 ， 对 于 集群 而 言 ， 它 是 一 个 外 部 因素 。 
e NodeClient 
作为 ES 集群 的 一 个 节点 ， 它 是 ES 中 的 一 环 ， 其 他 的 节点 对 它 是 感知 的 。 
e XPackTransportClient : 
服务 安装 了 x-pack 插件 
重要 : 客户 端 版 本 应 该 和 服务 端 版 本 保持 一 至 


TransportClient 旨 在 被 Java 高 级 REST 客 户 端 取 代 ， 该 客户 端 执 行 HTTP 请 求 而 
不 是 序列 化 的 Java 请 求 。 在 即将 到 来 的 Elasticsearch 版 本 中 将 不 赞成 使 用 
TransportClient， 建 议 使 用 Java 高 级 REST 客 户 端 。 


上 面 的 警告 比较 夏 软 ， 但 是 在 5xx 版 本 中 使 用 还 是 没有 问题 的 ， 可 能 使 用 rest 
客户 端 兼容 性 更 好 做 一 些 。 


Elasticsearch Java Rest API 手册 


Transport Client 


不 设置 集群 名 称 
// on startup 


// 此 步骤 添加 IP， 至 少 一 个 ， 如 果 设 置 了 "clLient .transport.sniff"= true 一 
个 就 够 了 ， 因 为 添加 了 自动 嗅 探 配置 
TransportClient client = new PreBuiltTransportClient(Settings.EM 
PTY) 

.addTransportAddress(new InetSocketTransportAddress(Inet 
Address.getByName("host1"), 9300)) 

.addTransportAddress(new InetSocketTransportAddress(Inet 
Address.getByName("host2"), 9300)); 


// on shutdown 关闭 client 


client.close(); 


设置 集群 名 称 


Settings settings = Settings.builder() 

.put("cluster.name", "myClusterName").build(); //% EES 
实例 的 名 称 
TransportClient client = new PreBuiltTransportClient(settings); 
// 自 动 嗅 探 整 个 集群 的 状态 ， 把 集群 中 其 他 ES 节点 的 ip 添加 到 本 地 的 客户 端 列 表 中 
//Add transport addresses and do something with the client... 


增加 自动 噢 探 配 置 


Settings settings = Settings.builder() 
.put("client.transport.sniff", true).build(); 
TransportClient client - new PreBuiltTransportClient(settings); 


其 他 配置 


client.transport.ignore cluster name //itE true ， 忽 略 连接 节点 集群 


名 验证 
client.transport.ping timeout //ping 一 个 节点 的 响应 时 间 默认 5 秒 
client.transport.nodes sampler interval //sample/ping 节点 的 时 间 间 


隔 ， 上 默认 是 5S 


对 于 ES Client， 有 两 种 形式 ， 一 个 是 TransportClient， 一 个 是 NodeClient。 两 
个 的 区 别 为 : TransportClient 作 为 一 个 外 部 访问 者 ， 通 过 HTTP 去 请 求 ES 的 集 
群 ， 对 于 集群 而 言 ， 它 是 一 个 外 部 因素 。 NodeClient 顾 名 思 义 ， 是 作为 ES 集 
群 的 一 个 节点 ， 它 是 ES 中 的 一 环 ， 其 他 的 节点 对 它 是 感知 的 ， 不 像 
TransportClient 那 样 ，ES 集 群 对 它 一 无 所 知 。NodeClient 通 信 的 性 能 会 更 好 ， 
但 是 因为 是 ES 的 一 环 ， 所 以 它 出 问题 ， 也 会 给 ES 集群 带 来 问题 。NodeClient 
可 以 设置 不 作为 数据 节点 ， 在 elasticsearch.yml 中 设置 ， 这 样 就 不 会 在 此 节点 
上 分 配 数据 。 


如 果 用 ES 的 节点 ， 大 家 仁者 见 仁 智者 见 智 ， 各 按 所 需 。 
实例 


Settings esSettings = Settings.builder() 
.put("cluster.name", clusterName) // 设 置 ES 实例 的 名 称 


.put("client.transport.sniff", true) // 自 动 噢 探 整个 集群 的 状态 ， 
把 集群 中 其 他 ES 节点 的 ip 添加 到 本 地 的 客户 端 列 表 中 


.build()， 


client = new PreBuiltTransportclient(esSettings);// 初 始 化 clie 
nt 较 老 版 本 发 生 了 变化 ， 此 方法 有 几 个 重 载 方 法 ， 初 始 化 插件 等 。 


// 此 步骤 添加 IP， 至 少 一 个 ， 其 实 一 个 就 够 了 ， 因 为 添加 了 自动 噢 探 配置 


client.addTransportAddress(new InetSocketTransportAddress(In 
etAddress.getByName(ip), esPort)); 


Transport Client 
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XPackTransportClient 


如 果 ElasticSearch 服务 安装 了 x-pack 插件 ， 需 
要 PreBuiltXPackTransportClient 实例 才能 访问 


使 用 Maven 管 理 项 目 ， 把 下 面 代码 增加 到 pom.xml ; 


一 定 要 修改 默认 仓库 地 址 为 https://artifacts.elastic.co/maven ， 因 为 这 个 库 没有 
上 传 到 Maven 中 央 仓 库 


<project ...> 


<repositories> 
<!-- add the elasticsearch repo --> 
<repository> 
<id>elasticsearch-releases</id> 
<url>https://artifacts.elastic.co/maven</url> 


<releases> 
<enabled>true</enabled> 
</releases> 
<snapshots> 
<enabled>false</enabled> 
</snapshots> 
</repository> 
</repositories> 
<dependencies> 
<!-- add the x-pack jar as a dependency --> 
<dependency> 


<groupId>org.elasticsearch.client</groupId> 
<artifactId>x-pack-transport</artifactId> 
<version>5.6.3</version> 

</dependency> 


</dependencies> 


</project> 


实例 


更 


Settings settings = Settings.builder().put("cluster.name", "xxx" 
) 
.put("xpack.security.transport.ssl.enabled", 
false) 
.put("xpack.security.user", "xxx:xxx" 
.put("client.transport.sniff", true).build() 
/ 
try { 
client = new PreBuiltXPackTransportClient(settings) 
.addTransportAddress(new InetSocketTransportAddress( 
InetAddress .getByName("XXX.XXX.XXX.XXX"), 9300)) 
.addTransportAddress(new InetSocketTransportAddress( 
InetAddress.getByName("xxx.xxx.xxx.xxx"), 9300)); 
} catch (UnknownHostException e) { 
e.printStackTrace(); 


We 


多 请 浏览 dayu-spring-boot-starter 开源 项 目 


Document APIs 


Document APIs 


本 节 介 绍 以 下 CRUD API : 
单 文档 APIS 


e Index API 

e Get API 

e Delete API 

e Delete By Query API 
e Update API 


多 文档 APIs 


e Multi Get API 
e Bulk API 
e Using Bulk Processor 


Multi Get API Bulk API 


注意 :所 有 的 单 文档 的 CRUD API，index 参 数 只 能 接受 单一 的 索引 库 名 称 ， 或 者 
是 一 个 指向 单一 索引 库 的 alias。 
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Index API 


Index API 允许 我 们 存储 一 个 JSON 格 式 的 文档 ， 使 数据 可 以 被 搜索 。 文 档 通过 
index、type、id 唯 一 确定 。 我 们 可 以 自己 提供 一 个 id， 或 者 也 使 用 Index API 为 我 
们 自动 生成 一 个 。 
这 里 有 几 种 不 同 的 方式 来 产生 JSON 格 式 的 文档 (document) : 

e 手动 方式 ， 使 用 原生 的 byte[] 或 者 String 

e 使 用 Map 方 式 ， 会 自动 转换 成 与 之 等 价 的 JSON 

e 使 用 第 三 方 库 来 序列 化 beans， 如 Jackson 

e 使 用 内 置 的 帮助 类 XContentFactory.jsonBuilder() 


手动 方式 
数据 格式 
String json = "{" + 
"\"user\":\"kimchy\"," + 


"\"postDate\":\"2013-01-30\"," + 
"\"message\":\"trying out Elasticsearch\"" + 


MEM 


实例 


/** 
* 手动 生成 JSON 
af 

@Test 

public void CreateJSON(){ 


String json = "{" + 
"\Muser\":\"fendo\"," + 
"\"postDate\":\"2013-01-30\"," + 
"\"message\":\"Hell word\"" + 


EPN 


IndexResponse response = client.prepareIndex("fendo", 
date") 
.setSource(json) 
.get(); 
System.out.println(response.getResult()); 


Map7 X 


Map 是 key:value 数 据 类 型 ， 可 以 代表 json 结 构 . 
Map<String, Object> json = new HashMap<String, Object>(); 
json.put("user", "kimchy"); 


json.put("postDate",new Date()); 
json.put("message","trying out Elasticsearch"); 


实例 


"fendo 


per 
* 使 用 集合 
T 

QTest 

public void CreateList(){ 


Map<String, Object> json = new HashMap<String, Object>(); 
json.put("user", "kimchy"); 

json.put("postDate", "2013-01-30"); 
json.put("message","trying out Elasticsearch"); 


IndexResponse response - client.prepareIndex("fendo", "fendo 
date") 
.setSource(json) 


get(); 
System.out.println(response.getResult()); 


序列 化 方式 
ElasticSearch 已 经 使 用 了 jackson， 可 以 直接 使 用 它 把 javabean 转 为 json. 
import com.fasterxml.jackson.databind.*; 


// instance a json mapper 
ObjectMapper mapper - new ObjectMapper(); // create once, reuse 


// generate json 
byte[] json = mapper.writeValueAsBytes(yourbeaninstance); 


实例 


JR 
* 使 用 JACKSON 序 列 化 
* @throws Exception 
a 
QTest 
public void CreateJACKSON() throws Exceptionf 


CsdnBlog csdn=new CsdnBlog(); 
csdn.setAuthor("fendo"); 
csdn.setContent(" 这 是 JAVA 书籍 " ) ; 
csdn.setTag("C"); 
csdn.setView("100"); 
csdn.setTitile("##"); 
csdn.setDate(new Date().toString()); 


// instance a json mapper 
ObjectMapper mapper = new ObjectMapper(); // create once, re 
use 


// generate json 
byte[] json = mapper.writeValueAsBytes(csdn); 


IndexResponse response = client.prepareIndex("fendo", "fendo 
date") 
.setSource(json) 


get(); 
System.out.println(response.getResult()); 


XContentBuilder# 34 AF X, 


ElasticSearchd£ # f —*A & 49 38$ 34 RXContentBuilder* * JSON x: 4% 


// Index name 

String index - response.getIndex(); 

// Type name 

String type = response.getType( ); 

// Document ID (generated or not) 

String id - response.getId(); 

// Nersion (if it's the first time you index this document, you 
will get: 1) 

long version - response.getVersion(); 

// status has stored current instance statement. 
RestStatus status - response.status(); 


实例 


OA 
* 使 用 ElasticSearch 帮助 类 
* (throws IOException 
nu 
@Test 
public void CreateXContentBuilder() throws IOExceptionf 


XContentBuilder builder - XContentFactory.jsonBuilder() 
.startObject() 
.field("user", "ccse") 
.field("postDate", new Date()) 
.field("message", "this is Elasticsearch") 
.endObject(); 


IndexResponse response = client.preparelIndex("fendo", "fendo 
data").setSource(builder).get(); 
System.out.println("6|z X51"); 


import 
import 
import 
import 
import 
import 


import 
import 
import 
import 
ress; 
import 
import 
import 
t; 
import 
import 


import 
import 


public 


java. 
java. 
java. 
java. 
java. 
java. 


org. 
org. 
org. 
org. 


org 
org. 
org. 


org. 
org. 


com. 
com. 


util.Date; 


util.Map; 


elasticsearch. 
elasticsearch. 
elasticsearch. 
elasticsearch. 


.elasticsearch. 
elasticsearch. 
elasticsearch. 


junit.Before; 
junit.Test; 


util.HashMap; 


io.IOException; 
net.InetAddress; 


action. 
client. 
common . 
common. 


common 


common. 


net .UnknownHostException; 


index. IndexResponse; 
transport.TransportClient; 
settings.Settings; 
transport.InetSocketTransportAdd 


.Xcontent.XContentBuilder; 


xcontent.XContentFactory; 


transport.client.PreBuiltTransportClien 


fasterxml.jackson.core.JsonProcessingException; 


fasterxml.jackson.databind.ObjectMapper; 


class CreateIndex { 


private TransportClient client; 


@Before 
public void getClient() throws Exception{ 
// 设 置 集群 名 称 


j 


EXER 


Settings settings 


cli 


- Settings.builder().put("cluster.name 
", "my-application").build();// 集群 名 
//&|3£client 


ent = new PreBuiltTransportClient(settings) 


.addTransportAddress(new InetSocketTransportAddr 
ess(InetAddress.getByName("127.0.0.1"), 9300)); 


* 手动 生成 JSON 


=y 


QTest 
public void CreateJSON()( 


String json = "{" + 
""user\":\"fendo\"," + 
"\"jostDate\":\"2013-01-30\"," + 
"\"message\":\"Hell word\"" + 


ee 


IndexResponse response = client.prepareIndex("fendo", "f 
endodate" ) 
.setSource(json) 
.get(); 
System.out.println(response.getResult()); 


/** 
* 使 用 集合 
25 

QTest 

public void CreateList(){ 


Map<String, Object» json = new HashMap<String, Object>() 


json.put("user", "kimchy"); 
json.put("postDate", "2013-01-30"); 
json.put("message","trying out Elasticsearch"); 


IndexResponse response - client.prepareIndex("fendo", "f 
endodate") 
.setSource(json) 
.get(); 
System.out.println(response.getResult()); 


fees 
* 使 用 JACKSON 序 列 化 


* @throws Exception 
de 
QTest 
public void CreateJACKSON() throws Exceptionf 


CsdnBlog csdn=new CsdnBlog(); 
csdn.setAuthor("fendo"); 
csdn.setContent(" 这 是 JAVA 书籍 " ) ) 
csdn.setTag("C"); 
csdn.setView("100"); 
csdn.setTitile("##"); 
csdn.setDate(new Date().toString()); 


// instance a json mapper 
ObjectMapper mapper = new ObjectMapper(); // create once 


, reuse 


// generate json 
byte[] json = mapper.writeValueAsBytes(csdn); 


IndexResponse response = client.prepareIndex("fendo", "f 


endodate" ) 
.setSource(json) 
get(); 
System.out.println(response.getResult()); 
} 
/** 


* 使 用 ElasticSearch 帮助 类 
* (throws IOException 
us 
QTest 
public void CreateXContentBuilder() throws IOExceptionf 


XContentBuilder builder - XContentFactory.jsonBuilder() 


.startObject() 
.field("user", "ccse") 
.field("postDate", new Date()) 
.field("message", "this is Elasticsearch") 


.endObject(); 


IndexResponse response - client.prepareIndex("fendo", "f 
endodata").setSource(builder).get(); 
System.out.println("4|zt 1"); 


Ww 


= 


4 


y 


j 


$9» s 


“还 可 以 通过 startArray(string) 和 endArray() 方 法 添加 数组 。.field() 方 法 可 以 接 
痰 多 种 对 和 象 类 型 。 你 可 以 给 它 传 递 数 字 、 日 期 、 甚 至 其 他 XContentBuilder 对 


o 


Get API 


根据 jd 查看 文档 : 


GetResponse response = client.prepareGet("twitter", "tweet", "1" 
).get(); 


更 多 请 查看 rest get API 文档 


配置 线程 
operationThreaded 设置 为 true 是 在 不 同 的 线程 里 执行 此 次 操作 


下 面 的 例子 是 operationThreaded 设置 为 false 


GetResponse response = client.prepareGet("twitter", "tweet", "1" 


) 


.setOperationThreaded(false) 
.get (); 


Delete API 


根据 ID 删除 : 


DeleteResponse response = client.prepareDelete("twitter", "tweet 
O 


更 多 请 查看 delete API 文档 


配置 线程 
operationThreaded 设置 为 true 是 在 不 同 的 线程 里 执行 此 次 操作 


下 面 的 例子 是 operationThreaded 设置 为 false 


GetResponse response = client.prepareGet("twitter", "tweet", "1" 


) 


.setOperationThreaded(false) 
.get (); 


DeleteResponse response = client.prepareDelete("twitter", "tweet 
"y on") 

.setOperationThreaded(false) 

-get(); 


Delete By Query API 


通过 查询 条 件 删除 


BulkByScrollResponse response = 
DeleteByQueryAction.INSTANCE.newRequestBuilder(client) 
.filter(QueryBuilders.matchQuery("gender", "male")) //£& 


.source("persons") //index( #414) 
.get(); // 执 行 


long deleted = response.getDeleted(); // 删 除 文档 的 数量 
如 果 需 要 执行 的 时 间 比 较 长 ， 可 以 使 用 异步 的 方式 处 理 ,结果 在 回调 里 面 获取 


DeleteByQueryAction.INSTANCE.newRequestBuilder(client) 


.filter(QueryBuilders.matchQuery("gender", "male")) // 
查询 
.source("persons" ) //index( 512) 
.execute(new ActionListener<BulkByScrollResponse>() { // 
回调 监听 
@Override 
public void onResponse(BulkByScrollResponse response) { 
long deleted = response.getDeleted(); // 删 除 文档 的 数 
量 
} 
@Override 


public void onFailure(Exception e) { 
// Handle the exception 


+); 


Update API 


有 两 种 方式 更 新 索引 : 


e 创建 UpdateRequest ,通过 client 发 送 ; 
e 使 用 prepareUpdate() 方法 ; 


使 用 UpdateRequest 


UpdateRequest updateRequest = new UpdateRequest(); 
updateRequest.index("index"); 
updateRequest.type("type"); 
updateRequest.id("1"); 
updateRequest.doc(jsonBuilder() 

.startObject() 

.field("gender", "male") 

.endObject()); 

client.update(updateRequest).get(); 


使 用 prepareUpdate() 方法 


这 里 官方 的 示例 有 问题 ，new Script () 参数 错误 ， 所 以 一 下 代码 是 我 自己 写 
aJ (2017/11/10) 


client.prepareUpdate("tt1", "doc", "1") 

.setScript(new Script("ctx. source.gender = \"male\"" 
ScriptService.ScriptType.INLINE, null, null))//BpA s yAX Ax 4 
储 的 ， 如 果 使 用 文件 存储 的 脚本 ， 需 要 设置 ScriptService.ScriptType.FILE 

.get(); 


client.prepareUpdate("ttl", "doc", "1") 
.setDoc(jsonBuilder()  // 合 并 到 现 有 文档 
.startObject() 
.field("gender", "male") 
.endObject()) 


.get(); 


Update by script 


使 用 脚本 更 新 文档 


UpdateRequest updateRequest = new UpdateRequest("ttl", "doc", "1 


") 


.Script(new Script("ctx. source.gender = \"male\"")); 


client.update(updateRequest).get(); 


Update by merging documents 


合并 文档 


UpdateRequest updateRequest = new UpdateRequest("index", 
"4") 
.doc(jsonBuilder() 
.startObject() 
.field("gender", "male") 
.endObject()); 
client.update(updateRequest).get(); 


Upsert 


更 新 插入 ,如 果 存 在 文档 就 更 新 ， 如 果 不 存在 就 插入 


"type" e 


IndexRequest indexRequest = new IndexRequest("index", "type", "1 
") 
.Source(jsonBuilder() 
.startObject() 
.field("name", "Joe Smith") 
.field("gender", "male") 
.endObject()); 
UpdateRequest updateRequest - new UpdateRequest("index", "type", 
"4") 
.doc(jsonBuilder() 
.startObject() 
.field("gender", "male") 
.endObject()) 
.upsert(indexRequest); // 如 果 不 存 在 此 文档 ， 就 增加 “IndexReq 
uest' 
client.update(updateRequest).get(); 


如 果 index/type/1 存在 ， 类 似 下 面 的 文档 : 


"name" : "Joe Dalton", 
"gender": "male" 


如 果 不 存在 ， 会 插入 新 的 文档 : 


"name" : "Joe Smith", 
"gender": "male" 


Multi Get API 
一 次 获取 多 个 文档 


MultiGetResponse multiGetItemResponses = client.prepareMultiGet( 
) 
.add("twitter", "tweet", "1") // 一 个 id 的 方式 
.add( "twitter", "tweet", "2", "3", 14") // 多 个 id 的 方式 
.add("another", "type", "foo") // 可 以 从 另外 一 个 索引 获取 
.get(); 


for (MultiGetItemResponse itemResponse : multiGetItemResponses) 
{ / /3R ANGR WM 
GetResponse response - itemResponse.getResponse(); 
if (response.isExists()) { // 判 断 是 否 存在 
String json = response.getSourceAsString(); // source + 


更 多 请 浏览 REST multi get 文档 


Bulk API 


Bulk API， 批 量 插入 : 


import static org.elasticsearch.common.xcontent.XContentFactory. 


ka 
, 


BulkRequestBuilder bulkRequest - client.prepareBulk(); 


// either use client#prepare, or use Requests# to directly build 
index/delete requests 
bulkRequest.add(client.prepareIndex("twitter", "tweet", "1") 
.setSource(jsonBuilder() 
.startObject() 
.field("user", "kimchy") 
.field("postDate", new Date()) 
.field("message", "trying out Elasticsea 
rch") 
.endObject() 


): 


bulkRequest.add(client.prepareIndex("twitter", "tweet", "2") 
. setSource(jsonBuilder ( ) 
.startObject() 
.field("user", "kimchy") 
.field("postDate", new Date()) 
.field("message", "another post") 
.endObject() 


yr 


BulkResponse bulkResponse = bulkRequest.get(); 
if (bulkResponse.hasFailures()) { 

// process failures by iterating through each bulk response 
item 

// 处 理 失败 


使 用 Bulk Processor 


BulkProcessor 提供 了 一 个 简单 的 接口 ， 在 给 定 的 大 小 数量 上 定时 批量 自动 请 求 


创建 BulkProcessor 实例 


首先 创建 BulkProcessor 实例 


Import 
Import 
Import 
Import 
Import 


org. 
org. 


org 


org. 
org. 


elasticsearch. 
elasticsearch. 


.elasticsearch. 


elasticsearch. 
elasticsearch. 


action. 
action. 


common 


common . 
common . 


bulk. 
bulk. 


.unit. 


unit. 
unit. 


BackoffPolicy; 
BulkProcessor; 
ByteSizeUnit; 
ByteSizeValue; 
TimeValue; 


BulkProcessor bulkProcessor - BulkProcessor.builder( 
client, //?$J«elasticsearch € P 35 
new BulkProcessor.Listener() ( 
@Override 
public void beforeBulk(long executionId, 
BulkRequest request) ( ... } 
// 调 用 bulk 之 前 执行 ， 例 如 你 可 以 通过 request.number0fActions() 方 法 知道 hu 
mberOfActions 


QOverride 
public void afterBulk(long executionId, 
BulkRequest request, 
BulkResponse response) { ... } 
// 调 用 bulk 之 后 执行 ， 例 如 你 可 以 通过 request.hasFailures() 方 法 知道 是 否 执 
行 失败 


QOverride 
public void afterBulk(long executionId, 
BulkRequest request, 
Throwable failure) ( ... } // 
调用 失败 抛 Throwable 
3) 
.setBulkActions(10000) // 每 次 10000 请 求 
.SetBulkSize(new ByteSizeValue(5, ByteSizeUnit.MB)) //4f 
成 5mb 一 块 
.setFlushInterval(TimeValue.timeValueSeconds(5)) // 无 论 请 
求 数量 多 少 ， 每 5 秒 钟 请 求 一 次 。 
.setConcurrentRequests(1) // 设 置 并 发 请 求 的 数量 。 值 为 9 意味 着 只 
允许 执行 一 个 请 求 。 值 为 1 意味 着 允许 1 并 发 请 求 。 
.setBackoffPolicy( 
BackoffPolicy.exponentialBackoff(TimeValue.timeValue 
Mil1is(1090)，3) )// 设 置 自 定义 重复 请 求 机 制 ， 了 最 开始 等 待 199 毫 秒 ， 之 后 成 倍 更 加 
， 重 试 3 次 ， 当 一 次 或 多 次 重复 请 求 失败 后 因为 计算 资源 不 够 抛 出 EsRejectedExecu 
tionException 了 异常， 可 以 通过 BackoffPo1lLicy.noBackoff() 方 法 关闭 重 试 机 制 
.build(); 


BulkProcessor 默认 设置 


e bulkActions 1000 


e bulkSize 5mb 

e 不 设置 flushlnterval 

e concurrentRequests 为 1， 异步 执行 
e backoffPolicy 重 试 8 次 ， 等 待 50 毫 秒 


增加 requests 


然后 增加 requests 到 BulkProcessor 


bulkProcessor.add(new IndexRequest("twitter", "tweet", "1").sour 
ce(/* your doc here */)); 
bulkProcessor.add(new DeleteRequest("twitter", "tweet", "2")); 


关闭 Bulk Processor 


当 所 有 文档 都 处 理 完成 ， 使 用 awaitClose X close 方法 关 
BH] BulkProcessor : 


bulkProcessor.awaitClose(10, TimeUnit.MINUTES); 
或 


bulkProcessor.close(); 


在 测试 中 使 用 Bulk Processor 


如 果 你 在 测试 种 使 用 Bulk Processor 可 以 执行 同步 方法 


BulkProcessor bulkProcessor - BulkProcessor.builder(client, new 


BulkProcessor.Listener() { /* Listener methods */ }) 
.setBulkActions(10000) 
.setConcurrentRequests(0) 

.build( ); 


// Add your requests 
bulkProcessor.add(/* Your requests */); 


// Flush any remaining requests 
bulkProcessor.flush(); 


// Or close the bulkProcessor if you don't need it anymore 
bulkProcessor.close(); 


// Refresh your indices 
client.admin().indices().prepareRefresh().get(); 


// Now you can start searching! 
client.prepareSearch().get(); 


搜索 API 


搜索 查询 ， 返 回 查 询 匹配 的 结果 ， 搜 索 一 个 index / type 或 者 多 个 index /type， 可 
以 使 用 query Java API 作为 查询 条 件 ， 下 面 是 例子 : 


import org.elasticsearch.action.search.SearchResponse; 
import org.elasticsearch.action.search.SearchType; 
import org.elasticsearch.index.query.QueryBuilders.*; 


SearchResponse response = client.prepareSearch("indexi", "index2 
2) 
.setTypes("typei", "type2") 
.setSearchType(SearchType.DFS QUERY THEN FETCH) 
.setQuery(QueryBuilders.termQuery("multi", "test")) 
// Query 查询 条 件 
.setPostFilter(QueryBuilders.rangeQuery("age").from(12). 
to(18)) // Filter 过 滤 
.setFrom(0).setSize(60).setExplain(true) 
.get(); 


所 有 的 参数 都 是 可 选 的 ， 下 面 是 最 简单 的 调用 : 


// MatchAll on the whole cluster with all default options 
SearchResponse response - client.prepareSearch().get(); 


Rew Java API 默 认 提 供 QUERY AND FETCH 和 DFS QUERY AND FETCH 两 种 
search types ， 但 是 这 种 模式 应 该 由 系统 选择 ， 用 户 不 要 手动 指定 


更 多 请 移 步 REST search 文档 


Using scrolls in Java 


Using scrolls in Java 


首先 需要 阅读 scroll documentation 


一 般 搜 索 请 求 都 是 返回 一 "页 "数据 ， 无 论 数据 量 多 大 都 一 起 返回 给 用 户 ，Scroll 
API 可 以 允许 我 们 检索 大 量 数据 (甚至 全 部 数据 ) © Scroll API 人 允许 我 们 做 一 个 
初始 阶段 搜索 并 且 持 续 批 量 从 Elasticsearch 里 拉 取 结果 直到 没有 结果 剩 下 。 这 
有 点 像 传统 数据 库 里 的 cursors (游标 ) 。 Scroll API 的 创建 并 不 是 为 了 实时 的 
用 户 响应 ， 而 是 为 了 处 理 大 量 的 数据 〈Scrolling is not intended for real time 
user requests, but rather for processing large amounts of data) °- M scroll 请 
求 返回 的 结果 只 是 反映 了 search 发 生 那 一 时 刻 的 索引 状态 ， 就 像 一 个 快照 
(The results that are returned from a scroll request reflect the state of the 
index at the time that the initial search request was made, like a snapshot in 
time)。 后 续 的 对 文档 的 改动 (索引 、 更 新 或 者 删除 ) 都 只 会 影响 后 面 的 搜索 请 


import static org.elasticsearch.index.query.QueryBuilders.*; 


QueryBuilder qb - termQuery("multi", "test"); 


SearchResponse scrollResp - client.prepareSearch(test) 
.addSort(FieldSortBuilder.DOC FIELD NAME, SortOrder.ASC) 
.setScroll(new TimeValue(60000)) // 为 了 使 用 scroll» 774648 

索 请 求 应 该 在 查询 中 指定 scroll 参数 ， 告 诉 Elasticsearch 需要 保持 搜索 的 上 

下 文 环 境 多 长 时 间 (滚动 时 间 ) 

.setQuery(qb) 
.setSize(100).get(); //max of 100 hits will be returned 
for each scroll 

//Scroll until no hits are returned 

do { 

for (SearchHit hit : scrollResp.getHits().getHits()) { 
//Handle the hit... 


scrollResp - client.prepareSearchScroll(scrollResp.getScroll 
Id()).setScroll(new TimeValue(60000)).execute().actionGet(); 
) while(scrollResp.getHits().getHits().length != 0); // Zero hit 
s mark the end of the scroll and the while loop. 


如 果 超 过 滚动 时 间 ， 继 续 使 用 该 滚动 ID 搜索 数据 ， 则 会 报错 : 


Caused by: SearchContextMissingException[No search context found 
for id [2861]] 

at org.elasticsearch.search.SearchService.findContext(Search 
Service.java:613) 

at org.elasticsearch.search.SearchService.executeQueryPhase( 
SearchService.java:403) 

at org.elasticsearch.search.action.SearchServiceTransportAct 
ion$SearchQueryScrollTransportHandler.messageReceived(SearchServ 
iceTransportAction.java:384) 

at org.elasticsearch.search.action.SearchServiceTransportAct 
ion$SearchQueryScrollTransportHandler.messageReceived(SearchServ 
iceTransportAction.java:381) 

at org.elasticsearch.transport.TransportRequestHandler.messa 
geReceived(TransportRequestHandler.java:33) 

at org.elasticsearch.transport.RequestHandlerRegistry.proces 
sMessageReceived(RequestHandlerRegistry.java:75) 

at org.elasticsearch.transport.TransportService$4.doRun(Tran 
sportService.java:376) 

at org.elasticsearch.common.util.concurrent.AbstractRunnable 
.run(AbstractRunnable.java:37) 

at java.util.concurrent.ThreadPoolExecutor.runwWorker(ThreadP 
oolExecutor.java:1142) 

at java.util.concurrent.ThreadPoolExecutor$Worker.run(Thread 
PoolExecutor.java:617) 

at java.lang.Thread.run(Thread.java:745) 


虽然 当 滚 动 有 效 时 间 已 过 ， 搜 索 上 下 文 (Search Context) 会 自动 被 清除 ， 但 是 
一 值 保 持 滚 动 代价 也 是 很 大 的 ， 所 以 当 我 们 不 在 使 用 滚动 时 要 尽快 使 用 Clear- 
Scroll API 进 行 清除 。 


清除 Scroll 


per 
* 清除 滚动 ID 
* @param client 
* param scrollIdList 
* Qreturn 
A 
public static boolean clearScroll(Client client, List<String 
> scrollIdList)( 
ClearScrollRequestBuilder clearScrollRequestBuilder = cl 
ient.prepareClearScroll(); 
clearScrollRequestBuilder.setScrollIds(scrollIdList); 
ClearScrollResponse response - clearScrollRequestBuilder 
.get(); 
return response.isSucceeded(); 
} 
/** 
* 清除 滚动 ID 
* @param client 
* (param scrollId 
* @return 
a 
public static boolean clearScroll(Client client, String scro 
llid)( 
ClearScrollRequestBuilder clearScrollRequestBuilder - cl 
ient.prepareClearScroll(); 
clearScrollRequestBuilder.addScrollId(scrollId); 
ClearScrollResponse response - clearScrollRequestBuilder 
.get(); 
return response. isSucceeded(); 


实例 


public class ScrollsAPI extends ElasticsearchClientBase { 


private String scrollId; 


QTest 
public void testScrolls() throws Exception ( 


SearchResponse scrollResp - client.prepareSearch("twitte 
re) 
.addSort(FieldSortBuilder.DOC FIELD NAME, SortOr 
der.ASC) 
.setScroll(new TimeValue(60000)) // 为 了 使 用 scrol 
1]， 初 始 搜 索 请 求 应 该 在 查询 中 指定 scroll 和 参数， 告诉 Elasticsearch 需要 保持 
搜索 的 上 下 文 环 境 多 长 时 间 (滚动 时 间 ) 
.setQuery(QueryBuilders.termQuery("user", "kimch 
y")) // Query 查询 条 件 
.setSize(5).get(); //max of 100 hits will be ret 
urned for each scroll 
//Scroll until no hits are returned 


scrollId - scrollResp.getScrollId(); 
do { 
for (SearchHit hit : scrollResp.getHits().getHits()) 


//Handle the hit... 


System.out.println("" + hit.getSource().toString 
O); 


scrollResp = client.prepareSearchScroll(scrollid).se 
tScroll(new TimeValue(60000)).execute().actionGet(); 
j 
while (scrollResp.getHits().getHits().length != 0); // Z 
ero hits mark the end of the scroll and the while loop. 


} 


@Override 
public void tearDown() throws Exception { 
ClearScrollRequestBuilder clearScrollRequestBuilder = cl 
ient.prepareClearScroll(); 
clearScrollRequestBuilder.addScrollId(scrollId); 
ClearScrollResponse response - clearScrollRequestBuilder 


.get(); 


if (response.isSucceeded()) { 
System.out .printlLn(" 成 功 清除 " ) ; 


super.tearDown(); 


e ScrollsAPI.java 


e 本 手册 完整 实例 


MultiSearch API 


multi search API 允许 在 同一 API 中 执行 多 个 搜索 请 求 。 它 的 端点 (endpoint) X 
_msearch ° 


首先 请 看 MultiSearch API Query 文档 


SearchRequestBuilder srb1 = client 
.prepareSearch().setQuery(QueryBuilders.queryStringQuery("el 

asticsearch")).setSize(1); 

SearchRequestBuilder srb2 - client 
.prepareSearch().setQuery(QueryBuilders.matchQuery("name", " 

kimchy")).setSize(1); 


MultiSearchResponse sr - client.prepareMultiSearch() 
.add(srb1) 
.add(srb2) 
.get(); 


// You will get all individual responses from MultiSearchRespons 
ezgetResponses() 
long nbHits - 0; 
for (MultiSearchResponse.Item item : sr.getResponses()) ( 
SearchResponse response - item.getResponse(); 
nbHits += response.getHits().getTotalHits(); 


实例 
e MultiSearchAPI.java 


e 本 手册 完整 实例 


Using Aggregations 
下 面 的 代码 演示 了 如 何在 搜索 中 添加 两 个 聚合 : 


聚合 框架 有 助 于 根据 搜索 查询 提供 聚合 数据 。 它 是 基于 简单 的 构建 块 也 称 为 整 
合 ， 整 合 就 是 将 复杂 的 数据 摘要 有 序 的 放 在 一 块 。 


聚合 可 以 被 看 做 是 从 一 组 文件 中 获取 分 析 信 息 的 一 系列 工作 的 统称 。 聚 合 的 实 
现 过 ASA 个 文档 集 的 过 程 (例如 ， 在 搜索 请 求 的 基础 上 ， 执 行 查询 /过 
滤 ， 才 能 得 到 高 水 平 的 聚合 结果 ) > 


SearchResponse sr = client.prepareSearch() 
.setQuery(QueryBuilders.matchAllQuery()) 
.addAggregation( 

AggregationBuilders.terms("agg1").field("field”) 

) 
.addAggregation( 

AggregationBuilders.dateHistogram("agg2") 
.field("birth") 
.dateHistogramInterval(DateHistogramInterval 

. YEAR) 

) 
.get(); 


// Get your facet results 


Terms aggi = sr.getAggregations().get("agg1"); 
Histogram agg2 - sr.getAggregations().get("agg2"); 


详细 文档 请 看 Aggregations Java API 


Terminate After 


获取 文档 的 最 大 数量 ， 如 果 设 置 了 ， 需 要 通过 SearchResponse 对 象 里 
的 isTerminatedEarly() 判断 返回 文档 是 否 达到 设置 的 数量 : 


SearchResponse Sr = client.prepareSearch(INDEX) 
.SetTerminateAfter(1000) // 如 果 达 到 这 个 数量 ， 提 前 终止 
‘get(); 


if (sr.isTerminatedEarly()) { 
// We finished early 


Search Template 


首先 查看 Search Template 文档 
| search/template endpoint 允许 我 们 在 执行 搜索 请 求 和 使 用 模板 参数 十 充 现 有 
模板 之 前 ， 能 够 使 用 mustache 语言 预先 呈现 搜索 请 求 。 


将 模板 参数 定义 为 Map «String > Object» 


Map<String, Object> template params = new HashMap<>(); 
template params.put("param gender", "male"); 


可 以 在 config/scripts 中 使 用 存储 的 search templates ° 例如， 有 一 个 名 
为 config/scripts/template gender.mustache 的 文件 ， 其 中 包含 : 


"query" : ( 
"match" : { 
"gender" : n" 


创建 search templates 请 求 : 


SearchResponse sr = new SearchTemplateRequestBuilder(client) 
.setScript("template gender") //template % 
.setScriptType(ScriptService.ScriptType.FILE) //template 存储 

在 gender template.mustache 磁盘 上 


.setScriptParams(template params) //5 

.setRequest(new SearchRequest()) // 设 置 执行 的 cont 
ext (ie: 这 里 定义 索引 名 称 ) 

.get() 


.getResponse( ); 


还 可 以 将 template 存储 在 cluster state Y: 


cluster state 是 全 局 性 信息 , 包含 了 整个 群集 中 所 有 分 片 的 元 信息 (规则 , 位 置 , 大 
小 等 信息 ), 并 保持 每 人 、 每 节 的 信 ae 《为 什么 ElasticSearch 应 用 


开发 者 需要 了 解 cluster state》 


client.admin().cluster().preparePutStoredScript() 

.setScriptLang("mustache") 
.setId("template gender") 
.setSource(new BytesArray( 

a ss 

2 \"query\" : {\n" + 

i \"match\" : {\n" + 

a \"gender\" : \"\"An" + 

i }J\n" + 

A) AO 

"3")) get (); 


使 用 ScriptService.ScriptType.STORED 执行 一 个 存储 的 templates : 


SearchResponse Sr = new SearchTemplateRequestBuilder(client) 


.setScript("template gender") //template 名 

.setScriptType(ScriptType.STORED) //template 存储 在 
cluster state 上 

.setScriptParams(template params) //5 

.setRequest(new SearchRequest()) // 设 置 执行 的 context 
(ie: 这 里 定义 索引 名 称 ) 

.get() // 执 行 获取 template 


请 求 


.getResponse( ); 


也 可 以 执行 内 联 ( inline ) templates 


sr - new SearchTemplateRequestBuilder(client) 


.setScript("{\n" + //template 
名 
H \"query\" : {\n" + 
H \"match\" : {\n" + 
úl \"gender\" : NUN Nn" + 
E }J\n" + 
$ }J\n" + 
EPE) 
.setScriptType(ScriptType.INLINE) //template 是 内 联 传递 
的 
.setScriptParams(template params) / / BR 
.setRequest(new SearchRequest()) // 设 置 执行 的 context ( 
ie: 这 里 定义 索引 名 称 ) 
.get() // 执 行 获取 template 请 
X 


. getResponse( ); 


Aggregations 


又 
聚合 


> 


Elasticsearch4£ £t Z% 4 Java API 来 使 用 聚合 。 请 参阅 聚合 指南 。 


使 用 AggregationBuilders 构建 对 象 ， 增 加 到 搜索 请 求 中 : 


import org.elasticsearch.search.aggregations.AggregationBuilders 


, 


SearchResponse sr - node.client().prepareSearch() 
.setQuery( /* your query */ ) 
.addAggregation( /* add an aggregation */ ) 
.execute().actionGet(); 


Structuring aggregations 
结构 化 聚合 
如 Aggregations guide 中 所 述 ， 可 以 在 聚合 中 定义 子 聚合 。 


聚合 可 能 是 Metrics 聚合 (一 个 跟踪 和 计算 指标 的 聚合 ) 或 者 Bucket RS ( 构 
建 桶 聚合 ) 


例如 ， 这 里 是 一 个 3 级 聚合 组 成 的 聚合 : 


e Terms aggregation (bucket) 
e Date Histogram aggregation (bucket) 
e Average aggregation (metric) 


SearchResponse sr - node.client().prepareSearch() 
.addAggregation( 
AggregationBuilders.terms("by country").field("country") 
.subAggregation(AggregationBuilders.dateHistogram("by ye 
ar") 
.field("dateOfBirth") 
.dateHistogramInterval(DateHistogramInterval.YEAR) 
.subAggregation(AggregationBuilders.avg("avg childre 
n").field("children") ) 
) 
) 


.execute().actionGet(); 


Metrics aggregations 


计算 度量 这 类 的 聚合 操作 是 以 使 用 一 poe ab ie ade 
基础 的 。 这 些 数 据 不 但 可 以 从 文档 (使 用 数据 属性 ) 的 属性 中 提取 出 来 ， 也 可 
以 使 用 脚本 生成 。 


数值 计量 聚合 操作 是 能 够 产生 具体 的 数值 的 一 种 计量 聚合 操作 。 一 些 聚 合 操作 
输出 单个 的 计量 数值 (例如 avg) ， 并 且 被 称 作 single-value numeric metric 
aggregation， 其 他 产生 多 个 计量 数值 (例如 stats) 的 称 作 multi-value 
numeric metrics aggregation。 这 两 种 不 同 的 聚合 操作 只 有 在 桶 聚合 的 子 聚合 
操作 中 才 会 有 不 同 的 表现 (有 些 桶 有 聚合 可 以 基于 每 个 的 数值 计量 来 对 返回 的 桶 
进行 排序 ) 。 


Min Aggregatione x a+ 
下 面 是 如 何 用 Java API 使 用 最 小 值 聚 合 
准备 聚合 请 求 
下 面 是 如 何 创建 聚合 请 求 的 是 示例 : 
MinAggregationBuilder aggregation = 
AggregationBuilders 


.min("agg") 
.field("height"); 


使 用 聚合 请 求 


import org.elasticsearch.search.aggregations.metrics.min.Min; 


// sr is here your SearchResponse object 
Min agg = sr.getAggregations().get("agg"); 
double value - agg.getValue(); 


Max Aggregation R KERA 


下 面 是 如 何 用 Java API 4&8 JE] 3k X 4&8 46 
准备 聚合 请 求 


下 面 是 如 何 创 建 聚 合 请 求 的 是 示例 : 


MaxAggregationBuilder aggregation = 
AggregationBuilders 
.max("agg") 
.field("height"); 


使 用 聚合 请 求 


import org.elasticsearch.search.aggregations.metrics.max.Max; 


// sr is here your SearchResponse object 
Max agg = sr.getAggregations().get("agg"); 
double value - agg.getValue(); 


Sum Aggregation KA 
下 面 是 如 何 用 Java API 使 用 求 和 聚合 
准备 聚合 请 求 
下 面 是 如 何 创建 聚合 请 求 的 是 示例 : 
SumAggregationBuilder aggregation = 
AggregationBuilders 


.sum("agg") 
.field("height"); 


使 用 聚合 请 求 


import org.elasticsearch.search.aggregations.metrics.sum.Sum; 


// sr is here your SearchResponse object 
Sum agg - sr.getAggregations().get("agg"); 
double value - agg.getValue(); 


Avg Aggregation 平均 值 聚合 

下 面 是 如 何 用 Java API 使 用 平均 值 聚 合 

准备 聚合 请 求 

下 面 是 如 何 创 建 聚 合 请 求 的 是 示例 : 
AvgAggregationBuilder aggregation = 


AggregationBuilders 


.avg("agg") 
.field("height"); 


使 用 聚合 请 求 


import org.elasticsearch.search.aggregations.metrics.avg.Avg; 


// sr is here your SearchResponse object 
Avg agg = sr.getAggregations().get("agg"); 
double value - agg.getValue(); 


Stats Aggregation 统计 聚合 





RIBS 基于 文档 的 某 个 值 ， i Fa eka (min ^ max ^ sum ^ 
count ` avg) ,用 于 计算 的 值 可 以 是 特定 的 数值 型 字段 ， 也 可 以 通过 脚本 计算 


下 面 是 如 何 用 Java API 使 用 统计 有 聚合 


准备 聚合 请 求 


下 面 是 如 何 创建 聚合 请 求 的 是 示例 : 


StatsAggregationBuilder aggregation - 
AggregationBuilders 
.stats("agg") 
.field("height"); 


使 用 聚合 请 求 


import org.elasticsearch.search.aggregations.metrics.stats.Stats 


, 


// sr is here your SearchResponse object 
Stats agg - sr.getAggregations().get("agg"); 
double min - agg.getMin(); 

double max - agg.getMax(); 

double avg = agg.getAvg(); 

double sum = agg.getSum( ); 

long count = agg.getCount(); 


Extended Stats Aggregation 扩展 统计 聚合 


扩展 统计 聚合 基于 文档 的 茶 个 值 ， 计 草 出 一 些 统计 信息 〈 比 普通 的 stats 肥 


& $ f sum of squares、variance、std_deviation ` std deviation bounds) , 


用 于 计算 的 值 可 以 是 特定 的 数值 型 字段 ， 也 可 以 通过 脚本 计算 而 来 。 





下 面 是 如 何 用 Java API ER RARA 
准备 聚合 请 求 


下 面 是 如 何 创 建 聚 合 请 求 的 是 示例 : 


ExtendedStatsAggregationBuilder aggregation = 
AggregationBuilders 
.extendedStats("agg") 
.field("height"); 


使 用 聚合 请 求 


import org.elasticsearch.search.aggregations.metrics.stats.exten 
ded.ExtendedStats; 


// sr is here your SearchResponse object 
ExtendedStats agg - sr.getAggregations().get("agg"); 
double min = agg.getMin(); 

double max - agg.getMax(); 

double avg = agg.getAvg(); 

double sum = agg.getSum( ); 

long count = agg.getCount(); 

double stdDeviation - agg.getStdDeviation(); 

double sumOfSquares = agg.getSumOfSquares(); 

double variance - agg.getVariance(); 


Value Count Aggregation 值 计 数 采 合 





值 计数 聚合 个 值 的 个 数 , 用 于 计算 的 值 可 以 是 特定 的 数 
udo dde nuc dede 


noo singe: value 聚合 联合 使 用 ， 比 如 在 计算 一 个 字段 的 平均 值 
的 时 候 ， 可 能 还 会 关注 这 个 平均 值 是 由 多 少 个 值 计算 而 来 。 


下 面 是 如 何 用 Java API 使 用 值 计数 肥 合 


准备 聚合 请 求 


下 面 是 如 何 创建 聚合 请 求 的 是 示例 : 
ValueCountAggregationBuilder aggregation = 
AggregationBuilders 


.count ("agg") 
.field("height"); 


使 用 聚合 请 求 


import org.elasticsearch.search.aggregations.metrics.valuecount. 
ValueCount; 


// sr is here your SearchResponse object 
ValueCount agg - sr.getAggregations().get("agg"); 
long value - agg.getValue(); 


Percentile Aggregation 4 7 & RA 





百 分 百 聚合 Da et ne 些 值 中 的 一 个 或 者 多 
个 NM 


信 百 分 比 , 用 于 计算 的 值 可 以 是 特定 的 数值 型 字 ao 


下 面 是 如 何 用 Java API 8 zr & RS 


准备 聚合 请 求 


下 面 是 如 何 创建 聚合 请 求 的 是 示例 : 


PercentilesAggregationBuilder aggregation = 
AggregationBuilders 
.percentiles("agg") 
.field("height"); 


可 以 提供 百 分 位 数 ， 而 不 是 使 用 默认 值 : 


PercentilesAggregationBuilder aggregation = 
AggregationBuilders 
.percentiles("agg") 
-field("height") 
.percentiles(1.0, 5.0, 10.0, 20.0, 30.0, 75.0, 9 
5.0, 99.0); 


使 用 聚合 请 求 


import org.elasticsearch.search.aggregations.metrics.percentiles 
.Percentile; 
import org.elasticsearch.search.aggregations.metrics.percentiles 
.Percentiles; 


// sr is here your SearchResponse object 

Percentiles agg = sr.getAggregations().get("agg"); 

// For each entry 

for (Percentile entry : agg) { 
double percent - entry.getPercent(); // Percent 
double value = entry.getValue(); // Value 


logger.info("percent [{}], value [{}]", percent, value); 


大 概 输 出 : 


percent [1.0], value [0.814338896154595] 

percent [5.0], value [0.8761912455821302] 
percent [25.0], value [1.173346540141847] 
percent [50.0], value [1.5432023318692198] 
percent [75.0], value [1.923915462033674] 
percent [95.0], value [2.2273644908535335] 
percent [99.0], value [2.284989339108279] 


Percentile Ranks Aggregation 百分比 等 级 聚合 


一 个 multi-value 指 标 聚 合 ， 它 通过 从 聚合 文档 中 提取 数值 来 计算 一 个 或 多 个 百 
分 比 。 这 些 值 可 以 从 特定 数值 字段 中 提取 ， 也 可 以 由 提供 的 脚本 生成 。 


注意 : 请 参考 百分比 (通常 ) 近视 值 (percentiles are (usually approximate) ) 

和 压缩 (Compression) 以 获得 关于 近视 值 的 建议 和 内 存 使 用 的 百分比 排 位 聚 

合 。 ino Ro n idi 比 。 例 如 ， 假 如 某 一 直 

大 于 等 于 被 观测 值 的 95%， 则 称 其 为 第 95 百 分 位 数 。 假 设 你 的 数据 由 网 页 加 载 
时 间 组 成 。 你 可 能 有 一 个 服务 协议 ， ee * 99% 页 面 
在 30ms 加 载 完 全 o 


下 面 是 如 何 用 Java API 使 用 百分比 等 级 聚合 
准备 聚合 请 求 


下 面 是 如 何 创建 聚合 请 求 的 是 示例 : 


PercentilesAggregationBuilder aggregation - 
AggregationBuilders 
.percentiles("agg") 
.field("height"); 


使 用 聚合 请 求 


import org.elasticsearch.search.aggregations.metrics.percentiles 
.Percentile; 

import org.elasticsearch.search.aggregations.metrics.percentiles 
.PercentileRanks; 


// sr is here your SearchResponse object 
PercentileRanks agg - sr.getAggregations().get("agg"); 
// For each entry 
for (Percentile entry : agg) { 
double percent - entry.getPercent(); // Percent 
double value = entry.getValue(); // Value 


logger.info("percent [{}], value [{}]", percent, value); 


大 概 输 出 : 


percent [29.664353095090945], value [1.24] 
percent [73.9335313461868], value [1.91] 
percent [94.40095147327283], value [2.22] 


H 


Cardinality Aggregation 基数 聚合 


基于 文档 的 某 个 值 ， 计 算 文档 非 重 复 的 个 数 (去 重 计数 ) 。。 这 些 值 可 以 从 特 
定数 值 字段 中 提取 ， 也 可 以 由 提供 的 脚本 生 EA: 


下 面 是 如 何 用 Java AP| 使 用 基数 有 聚合 


准备 聚合 请 求 


下 面 是 如 何 创 建 聚合 请 求 的 是 示例 : 


CardinalityAggregationBuilder aggregation = 
AggregationBuilders 
.cardinality("agg") 
.field("tags"); 


使 用 聚合 请 求 


import org.elasticsearch.search.aggregations.metrics.cardinality 


.Cardinality; 


// sr is here your SearchResponse object 
Cardinality agg - sr.getAggregations().get("agg"); 
long value - agg.getValue(); 


Geo Bounds Aggregation 23532 11 RAS 





地 理 边 界 聚 合 基于 文档 的 某 个 字段 (geo-point 类 型 字段 ) 
所 有 地 理 坐 标点 的 边界 【左上 和 角 / 右 下 角 坐 标点 ) > 


下 面 是 如 何 用 Java API 使 用 地 理 边 界 聚 合 


准备 聚合 请 求 


下 面 是 如 何 创 建 聚 合 请 求 的 是 示例 : 


GeoBoundsBuilder aggregation = 
GeoBoundsAggregationBuilder 
.geoBounds ("agg") 
.field("address.location") 
.wrapLongitude(true); 


使 用 聚合 请 求 


,计算 出 该 字段 


import org.elasticsearch.search.aggregations.metrics.geobounds.G 
eoBounds; 


// sr is here your SearchResponse object 

GeoBounds agg - sr.getAggregations().get("agg"); 

GeoPoint bottomRight - agg.bottomRight(); 

GeoPoint topLeft - agg.topLeft(); 

logger.info("bottomRight {}, topLeft {}", bottomRight, topLeft); 


大 概 会 输出 : 


bottomRight [40.70500764381921, 13.952946866893775], topLeft [53 
.49603022435221, -4.190029308156676] 


Top Hits Aggregation 3 5 L BC dx fà RE 





最 高 匹配 权 值 聚合 跟踪 聚合 中 相关 性 最 高 的 文档 。 该 聚合 一 般 用 做 sub- 
aggregation， 以 此 来 聚合 每 个 桶 中 的 最 高 匹配 的 文档 e 


下 面 是 如 何 用 Java AP| 使 用 最 高 匹配 权 值 聚合 


准备 聚合 请 求 


下 面 是 如 何 创 建 聚 合 请 求 的 是 示例 : 


AggregationBuilder aggregation = 
AggregationBuilders 
.terms("agg").field("gender") 
.subAggregation( 
AggregationBuilders.topHits("top") 


); 


大 多 数 标 准 的 搜索 选项 可 以 使 用 ， 比 如: from, size, sort , highlight , 


explain 


AggregationBuilder aggregation - 
AggregationBuilders 
.terms("agg").field("gender") 
. subAggregation( 
AggregationBuilders.topHits("top") 

.explain(true) 
.Size(1) 
.from(10) 

); 


使 用 聚合 请 求 


import org.elasticsearch.search.aggregations.bucket.terms.Terms; 
import org.elasticsearch.search.aggregations.metrics.tophits.Top 
Hits; 


// Sr is here your SearchResponse object 
Terms agg - sr.getAggregations().get("agg"); 


// For each entry 
for (Terms.Bucket entry : agg.getBuckets()) { 
String key - entry.getKey(); // bucket ke 


long docCount - entry.getDocCount(); // Doc count 
logger.info("key [{}], doc count [{}]", key, docCount); 


// We ask for top hits for each bucket 
TopHits topHits - entry.getAggregations().get("top"); 
for (SearchHit hit : topHits.getHits().getHits()) { 
logger.info(" -> id [{}], _source [{}]", hit.getId(), hi 
t.getSourceAsString()); 


j 


大 概 会 输出 : 


key [male], doc count [5107] 
-» id [AUnzSZze9k7PKXtq04x2], . source 
-> id [AUnzSZzj9k7PKXtqO04x4], | source 
-> id [AUnzSZzl9k7PKXtq04x5], | source 
key [female], doc count [4893] 
-> id [AUnzSZzM9k7PKXtqO4xy], | source 
-> id [AUnzSZzp9k7PKXtq04x8], | source 
-> id [AUnzSZOW9k7PKXtqOA4yS], . source 


Scripted Metric Aggregation 


[{"gender": 
[{"gender": 
[{"gender": 


[{"gender": 
[{"gender": 
: "female", ...}] 


[("gender" 


nado cc] 
"male", e .}] 
"male", T: .3] 


"female", ...}] 
"female", ...}] 


此 功能 为 实验 性 的 ， 不 建议 生产 使 用 ， 所 以 也 不 做 过 多 说 明 有 兴趣 可 以 自己 参 


考 官方 文档 


Bucket aggregations 


Bucket aggregations 1427 7& 


Bucket aggregations 不 像 metrics aggregations 那样 计算 指标 ， 恰 恰 相 反 ， 它 
创建 文档 的 buckets， 每 个 buckets 与 标准 (取决 于 聚合 类 型 ) 相关 联 ， 它 决定 
了 当前 上 下 文中 的 文档 是 否 会 “falls" 到 它 。 换 名 话说 ，bucket 可 以 有 效 地 定义 文 

档 集 合 。 除 了 buckets 本 身 ，bucket 集 合 还 计算 并 返回 “ 落 入 "每 个 bucket 的 文档 

RE © 

与 度量 聚合 相 比 ，Bucket 聚 合 可 以 保存 子 聚合 ， 这 些 子 聚合 将 针对 由 

LS "bucketk > 6| 4) buckets {TRS © 

A F A bucketR+ S > 4 RU FF A “bucketing’R%, — 2 CL — N$ 3 83 
bucket， 一 些 定义 多 个 bucket 的 国定 数量 ， 另 一 些 定 义 在 聚合 过 程 中 动态 创建 
bucket 


Global Aggregation 全 局 采 合 


搜索 的 文档 类 型 定 e oa 。 


全 局 聚合 器 只 能 作为 顶层 聚合 器 放置 ， 因 为 将 全 局 聚合 器 诅 入 到 另 一 个 分 组 聚 


合 器 中 是 没有 意义 的 。 
下 面 是 如 何 使 用 Java API 使 用 全 局 聚合 
准备 聚合 请 求 


下 面 是 如 何 创 建 聚合 请 求 的 是 示例 : 


AggregationBuilders 

.global("agg") 

. subAggregation(AggregationBuilders.terms("genders").field(" 
gender" )); 


使 用 聚合 请 求 


64 


import org.elasticsearch.search.aggregations.bucket.global.Globa 
1; 


// sr is here your SearchResponse object 
Global agg = sr.getAggregations().get("agg"); 
agg.getDocCount(); // Doc count 


Filter Aggregation 331% RS 


ENE 
过 滤 有 聚合 


o 


基于 一 个 条 件 ， 来 对 当前 的 文档 进行 过 滤 的 聚 





下 面 是 如 何 使 用 Java API 使 用 过 滤 聚 合 
准备 聚合 请 求 
下 面 是 如 何 创 建 聚 合 请 求 的 是 示例 : 


AggregationBuilders 
.filter("agg", QueryBuilders.termQuery("gender", "male")); 


使 用 聚合 请 求 


import org.elasticsearch.search.aggregations.bucket.filter.Filte 
r; 


// sr is here your SearchResponse object 
Filter agg = sr.getAggregations().get("agg"); 
agg.getDocCount(); // Doc count 


Filters Aggregation 2 4 RS 


£i WR AR pa 合 





基于 多 个 过 滤 条 件 ， 来 对 当前 文档 进行 【过 滤 】 的 聚合 ， 每 个 
过 滤 都 包含 所 有 满足 它 的 文档 (多 个 bucket 中 可 能 重复 ) © 


下 面 是 如 何 使 用 Java API 使 用 多 过 滤 聚 合 


准备 聚合 请 求 


下 面 是 如 何 创 建 聚 合 请 求 的 是 示例 : 


AggregationBuilder aggregation = 
AggregationBuilders 
.filters("agg", 
new FiltersAggregator.KeyedFilter("men", QueryBuilde 
rs.termQuery("gender", "male")), 
new FiltersAggregator.KeyedFilter("women", QueryBuil 
ders.termQuery("gender", "female"))); 


使 用 聚合 请 求 
import org.elasticsearch.search.aggregations.bucket.filters.Filt 
ers; 
// Sr is here your SearchResponse object 
Filters agg - sr.getAggregations().get("agg"); 


// For each entry 
for (Filters.Bucket entry : agg.getBuckets()) { 


String key - entry.getKeyAsString(); // bucket ke 
y 
long docCount - entry.getDocCount(); // Doc count 
logger.info("key [(3], doc count [{}]", key, docCount); 
j 
大 概 输 出 


key [men], doc count [4982] 
key [women], doc count [5018] 


Missing Aggregation 基于 字段 数据 的 单 桶 聚合 


基于 字段 数据 的 单 桶 聚合 ， 创 建 当前 文档 集 上 下 文中 缺少 字段 值 的 所 有 文档 的 
bucket (44) (有 效 地 ， 丢 失 了 一 个 字段 或 配置 了 NULL 值 集 ) ， 此 聚合 器 通常 
与 其 他 字段 数据 桶 聚合 器 (例如 范围 ) 结合 使 用 ， 以 返回 由 于 缺少 字段 数据 值 
而 无 法 放置 在 任何 其 他 存储 区 中 的 所 有 文档 的 信息 。 


下 面 是 如 何 使 用 Java API 使 用 基于 字段 数据 的 单 桶 聚合 
准备 聚合 请 求 


下 面 是 如 何 创建 聚合 请 求 的 是 示例 : 


AggregationBuilders.missing("agg").field("gender"); 


使 用 聚合 请 求 


import org.elasticsearch.search.aggregations.bucket.missing.Miss 


ing; 


// sr is here your SearchResponse object 
Missing agg = sr.getAggregations().get("agg"); 
agg.getDocCount(); // Doc count 


Nested Aggregation 4 £ 3 7! RS 


LTH (nested) MAM > dei [em dE A] RO SIE AR R 
后 就 可 以 对 吝 套 类 型 做 进一步 的 聚合 操作 。 


下 面 是 如 何 使 用 Java API 使 用 吝 套 类 型 聚合 
准备 聚合 请 求 


下 面 是 如 何 创建 聚合 请 求 的 是 示例 : 


AggregationBuilders 
.nested("agg", "resellers"); 


使 用 聚合 请 求 


import org.elasticsearch.search.aggregations.bucket.nested.Neste 
d; 


// sr is here your SearchResponse object 
Nested agg = sr.getAggregations().get("agg"); 


agg.getDocCount(); // Doc count 


聚合 可 以 


Reverse nested Aggregation 
一 个 特殊 的 单 桶 有 聚合， 可 以 从 赂 套 文档 中 采 合 AUG 
Mik EAD P683 p IG AA > FRA ARA Bay 4533 SUR SUB RAT EUR 

A Gd dC REG Fo reverse nested 聚合 必须 定义 在 


RR 


父 文档 。 实 际 上 ， 这 种 


套 对 象 的 一 部 分 的 其 他 


nested 之 中 
下 面 是 如 何 使 用 Java API 使 用 Reverse nested Aggregation 


准备 聚合 请 求 
下 面 是 如 何 创 建 聚合 请 求 的 是 示例 : 


AggregationBuilder aggregation 


AggregationBuilders 
.nested("agg", "resellers") 
. subAggregation( 
AggregationBuilders 
.terms("name").field("resellers.name") 
.subAggregation( 
AggregationBuilders 
.reverseNested("reseller 
.to product") 
) 


); 


使 用 聚合 请 求 


import org.elasticsearch.search.aggregations.bucket.nested.Neste 
d; 

import org.elasticsearch.search.aggregations.bucket.nested.Rever 
seNested; 

import org.elasticsearch.search.aggregations.bucket.terms.Terms; 


// sr is here your SearchResponse object 
Nested agg - sr.getAggregations().get("agg"); 
Terms name - agg.getAggregations().get("name"); 


for (Terms.Bucket bucket : name.getBuckets()) { 

ReverseNested resellerToProduct - bucket.getAggregations().g 
et("reseller to product"); 

resellerToProduct.getDocCount(); // Doc count 


Children Aggregation 
一 种 特殊 的 单 桶 聚合， 可 以 将 父 文档 类 型 上 的 桶 有 聚合 到 子 文档 上 。 
下 面 是 如 何 使 用 Java API 使 用 Children Aggregation 
准备 聚合 请 求 
下 面 是 如 何 创建 聚合 请 求 的 是 示例 : 


AggregationBuilder aggregation = 
AggregationBuilders 


e 


.children("agg", "reseller"); // agg =X 484 » reseller 是 


fe 


FRM 


使 用 聚合 请 求 


import org.elasticsearch.join.aggregations.Children; 


// sr is here your SearchResponse object 
Children agg - sr.getAggregations().get("agg"); 
agg.getDocCount(); // Doc count 


Terms Aggregation 词 元 有 聚合 


基于 某 个 field， 该 field 内 的 每 一 个 【唯一 词 元 】 为 一 个 桶 ， 并 计算 每 个 桶 内 文 
档 个 数 。 黑 认 返 回 顺序 是 按照 文档 个 数 多 少 排序 。 当 不 返回 所 有 buckets 的 情 
况 ， 文 档 个 数 可 能 不 准确 。 


下 面 是 如 何 使 用 Java API 使 用 Terms Aggregation 
准备 聚合 请 求 


下 面 是 如 何 创 建 聚合 请 求 的 是 示例 : 


AggregationBuilders 
.terms("genders") 
.field("gender"); 


使 用 聚合 请 求 


import org.elasticsearch.search.aggregations.bucket.terms.Terms; 


// sr is here your SearchResponse object 
Terms genders - sr.getAggregations().get("genders"); 


// For each entry 

for (Terms.Bucket entry : genders.getBuckets()) (1 
entry.getKey(); // Term 
entry.getDocCount(); // Doc count 


Order 排序 


通过 doc count 按 升序 排列 : 


AggregationBuilders 
.terms("genders") 
.field("gender") 
.order(Terms.Order.count(true) ) 


按 字 词 顺 序 ， 升 序 排列 : 


AggregationBuilders 
.terms("genders") 
.field("gender") 
.order(Terms.Order.term(true)) 


d&metrics FREED (标示 为 聚合 名 ) 


AggregationBuilders 
.terms("genders") 
.field("gender") 
.order(Terms.Order.aggregation("avg height", false)) 
. subAggregation( 
AggregationBuilders.avg("avg height").field("height") 


Significant Terms Aggregation 

返回 集合 中 感 兴趣 的 或 者 不 常见 的 词 条 的 聚合 
下 面 是 如 何 使 用 Java API 使 用 Significant Terms Aggregation 
准备 聚合 请 求 


下 面 是 如 何 创 建 聚 合 请 求 的 是 示例 : 


AggregationBuilder aggregation - 
AggregationBuilders 
.significantTerms("significant countries") 
.field("address.country"); 


// Let say you search for men only 

SearchResponse sr - client.prepareSearch() 
.setQuery(QueryBuilders.termQuery("gender", "male")) 
.addAggregation(aggregation) 
.get(); 


使 用 聚合 请 求 


import org.elasticsearch.search.aggregations.bucket.significant. 
SignificantTerms; 


// sr is here your SearchResponse object 
SignificantTerms agg = sr.getAggregations().get("significant cou 
ntries"); 


// For each entry 

for (SignificantTerms.Bucket entry : agg.getBuckets()) (1 
entry.getKey(); // Term 
entry.getDocCount(); // Doc count 


Range Aggregation 范围 聚合 


3r 


基于 某 个 值 (可 以 是 field X script) » X [FARO] A482 7&6 OA 
包括 from 值 ， 不 包括 to 4& (区 间 前 闭 后 开 ) 。 


下 面 是 如 何 使 用 Java API 使 用 Range Aggregation 
准备 聚合 请 求 


下 面 是 如 何 创 建 聚 合 请 求 的 是 示例 : 


AggregationBuilder aggregation - 
AggregationBuilders 
.range("agg") 
.field("height") 


.addUnboundedTo(1.0f) // from -inf 
inity to 1.0 (excluded) 

.addRange(1.0f, 1.5f) // from 1.0 
to 1.5 (excluded) 

. addUnboundedFrom(1.5f); // from 1.5 


to +infinity 


使 用 聚合 请 求 


import org.elasticsearch.search.aggregations.bucket.range.Range; 


// Sr is here your SearchResponse object 
Range agg - sr.getAggregations().get("agg"); 


// For each entry 
for (Range.Bucket entry : agg.getBuckets()) { 


String key - entry.getKeyAsString(); // Range as 
key 
Number from - (Number) entry.getFrom(); // Bucket f 
rom 
Number to - (Number) entry.getTo(); // Bucket t 
O 
long docCount - entry.getDocCount(); // Doc count 


logger.info("key [{}], from [{}], to [{}], doc count [{}]", 
key, from, to, docCount); 


j 


key [*-1.0], from [-Infinity], to [1.0], doc count [9] 
key [1.0-1.5], from [1.0], to [1.5], doc count [21] 
key [1.5-*], from [1.5], to [Infinity], doc count [20] 


Date Range Aggregation 日 期 范围 聚合 


日 期 范围 聚合 基于 日 期 类 型 的 值 ， 以 【日 期 范围 】 来 桶 分 聚合 。 





日 期 范围 可 以 用 各 种 Date Math 表达 式 。 
同样 的 ， 包 括 from 的 值 ， 不 包括 to 的 值 。 


下 面 是 如 何 使 用 Java API 使 用 Date Range Aggregation 
准备 聚合 请 求 


下 面 是 如 何 创 建 聚 合 请 求 的 是 示例 : 


AggregationBuilder aggregation = 
AggregationBuilders 

.dateRange("agg") 

.field("dateOfBirth") 

.format("yyyy") 

.addUnboundedTo("1950") // from -infinity to 
1950 (excluded) 

.addRange("1950", "1960") // from 1950 to 1960 
(excluded) 

.addUnboundedFrom("1960"); // from 1960 to +infi 
nity 


使 用 聚合 请 求 


import org.elasticsearch.search.aggregations.bucket.range.Range; 


// sr is here your SearchResponse object 
Range agg = sr.getAggregations().get("agg"); 


// For each entry 
for (Range.Bucket entry : agg.getBuckets()) { 

String key = entry.getKeyAsString(); // Date 
range as key 

DateTime fromAsDate - (DateTime) entry.getFrom(); // Date 
bucket from as a Date 


DateTime toAsDate - (DateTime) entry.getTo(); // Date 
bucket to as a Date 

long docCount = entry.getDocCount(); // Doc c 
ount 


logger.info("key [{}], from [{}], to [{}], doc count [{}]", 
key, fromAsDate, toAsDate, docCount); 


key [*-1950], from [null], to [1950-01-01T00:00:00.000Z], doc co 
unt [8] 

key [1950-1960], from [1950-01-01T00:00:00.000Z], to [1960-01-01 
T00:00:00.000Z2], doc count [5] 

key [1960-*], from [1960-01-01T00:00:00.000Z], to [null], doc co 
unt [37] 


Ip Range Aggregation Ip it A RA 
下 面 是 如 何 使 用 Java API 使 用 Ip Range Aggregation 


准备 聚合 请 求 


PF Btw ERS HRY ETH : 


AggregatorBuilder«?» aggregation - 
AggregationBuilders 
.ipRange("agg") 
-field("ip") 
.addUnboundedTo("192.168.1.0") // fr 
om -infinity to 192.168.1.0 (excluded) 
. addRange( "192.168.1.0", "192.168.2.0") Vv qub 
om 192.168.1.0 to 192.168.2.0 (excluded) 
.addUnboundedFrom("192.168.2.0"); ULP OR 
om 192.168.2.0 to +infinity 


使 用 聚合 请 求 


import org.elasticsearch.search.aggregations.bucket.range.Range; 


// Sr is here your SearchResponse object 
Range agg - sr.getAggregations().get("agg"); 


// For each entry 
for (Range.Bucket entry : agg.getBuckets()) { 

String key - entry.getKeyAsString(); // Ip range 
as key 

String fromAsString = entry.getFromAsString(); // Ip bucket 
from as a String 

String toAsString - entry.getToAsString(); // Ip bucket 
to as a String 

long docCount - entry.getDocCount(); // Doc count 


logger.info("key [{}], from [{}], to [{}], doc count [{}]", 
key, fromAsString, toAsString, docCount); 


j 


key [*-1950], from [null], to [1950-01-01T00:00:00.000Z], doc co 
unt [8] 

key [1950-1960], from [1950-01-01T00:00:00.000Z], to [1960-01-01 
T00:00:00.0002], doc count [5] 

key [1960-*], from [1960-01-01T00:00:00.000Z], to [null], doc co 
unt [37] 


Histogram Aggregation 直方 图 有 聚合 


ES 


基于 文档 中 的 茶 个 【数值 类 型 】 字 段 ， 通 过 计算 来 动态 的 分 桶 。 
下 面 是 如 何 使 用 Java API 使 用 Histogram Aggregation 
准备 聚合 请 求 
下 面 是 如 何 创建 聚合 请 求 的 是 示例 : 
AggregationBuilder aggregation = 
AggregationBuilders 
.histogram("agg") 


.field("height") 
.interval(1); 


使 用 聚合 请 求 


import org.elasticsearch.search.aggregations.bucket.histogram.Hi 
stogram; 


// sr is here your SearchResponse object 
Histogram agg = sr.getAggregations().get("agg"); 


// For each entry 
for (Histogram.Bucket entry : agg.getBuckets()) { 
Number key = (Number) entry.getKey(); // Key 
long docCount - entry.getDocCount(); // Doc count 


logger.info("key [{}], doc count [{}]", key, docCount); 


Date Histogram Aggregation 日 期 范围 直方 图 聚合 
与 直方 图 类 似 的 多 bucket 聚 合 ， 但 只 能 应 用 于 日 期 值 .。 


下 面 是 如 何 使 用 Java API 使 用 Date Histogram Aggregation 


准备 聚合 请 求 


下 面 是 如 何 创建 聚合 请 求 的 是 示例 : 


AggregationBuilder aggregation = 
AggregationBuilders 
.dateHistogram("agg") 
.field("dateOfBirth") 
.dateHistogramInterval(DateHistogramInterval.YEA 
R); 


或 者 把 时 间 间 隔 设 置 为 10 天 


AggregationBuilder aggregation = 
AggregationBuilders 
.dateHistogram("agg") 
.field("dateOfBirth") 
.dateHistogramInterval(DateHistogramInterval.day 
s(10)); 


使 用 聚合 请 求 


import org.elasticsearch.search.aggregations.bucket.histogram.Hi 
stogram; 


// sr is here your SearchResponse object 
Histogram agg = sr.getAggregations().get("agg"); 


// For each entry 
for (Histogram.Bucket entry : agg.getBuckets()) { 
DateTime key = (DateTime) entry.getKey(); // Key 
String keyAsString = entry.getKeyAsString(); // Key as Strin 


long docCount = entry.getDocCount(); // Doc count 


logger.info("key [{}], date [{}], doc count [{}]", keyAsStri 
ng, key.getYear(), docCount); 


key [1942-01-01T00:00:00.000Z], date [1942], doc count [1] 
key [1945-01-01T00:00:00.000Z], date [1945], doc count [1] 
key [1946-01-01T00:00:00.000Z], date [1946], doc count [1] 


key [2005-01-01T00:00:00.000Z], date [2005], doc count [1] 
key [2007-01-01T00:00:00.000Z], date [2007], doc count [2] 
key [2008-01-01T00:00:00.000Z], date [2008], doc count [3] 


Geo Distance Aggregation +232 32 ARS 


在 geo_point 字 段 上 工作 的 多 bucket 聚 合 和 概念 上 的 工作 非常 类 似 于 range( 范 
围 ) 聚 合 . 用 户 可 以 定义 原点 的 点 和 距离 范围 的 集合 。 聚 合计 算 每 个 文档 值 与 原 
点 的 距离 ， 并 根据 范围 确定 其 所 属 的 bucket( 桶 ) (如 果 文档 和 原点 之 间 的 距离 
落 在 bucket( 桶 ) 的 距离 范围 内 ， 则 文档 属于 bucket( 桶 ) ) 


下 面 是 如 何 使 用 Java API 使 用 Geo Distance Aggregation 


准备 聚合 请 求 


下 面 是 如 何 创 建 聚 合 请 求 的 是 示例 : 


AggregationBuilder aggregation = 


AggregationBuilders 
.geoDistance("agg", new GeoPoint(48.842371711183 


14,2.33320027692004)) 


使 用 


.field("address.location") 
.unit(DistanceUnit.KILOMETERS) 
.addUnboundedTo(3.0) 
.addRange(3.0, 10.0) 
.addRange(10.0, 500.0); 


聚合 请 求 


import org.elasticsearch.search.aggregations.bucket.range.Range; 


// Sr is here your SearchResponse object 
Range agg - sr.getAggregations().get("agg"); 


// For each entry 
for (Range.Bucket entry : agg.getBuckets()) { 


String key - entry.getKeyAsString(); // key as String 
Number from - (Number) entry.getFrom(); // bucket from value 
Number to - (Number) entry.getTo(); // bucket to value 
long docCount = entry.getDocCount(); // Doc count 


logger.info("key [{}], from [{}], to [{}], doc count [{}]", 


key, from, to, docCount); 


key [*-3.0], from [0.0], to [3.0], doc count [161] 
key [3.0-10.0], from [3.0], to [10.0], doc count [460] 
key [10.0-500.0], from [10.0], to [500.0], doc count [4925] 


Geo Hash Grid Aggregation GeoHash 网 格 采 合 


在 geo_point 字 段 和 组 上 工作 的 多 bucket 有 聚合 将 指向 网 格 中 表示 单元 格 的 
bucket。 生 成 的 网 格 可 以 是 黎 牙 的 ， 并 且 只 包含 具有 匹配 数据 的 单元 格 。 每 个 
单元 格 使 用 具有 用 户 可 定义 精度 的 geohash 进行 标记 。 


下 面 是 如 何 使 用 Java API 使 用 Geo Hash Grid Aggregation 
准备 聚合 请 求 


下 面 是 如 何 创 建 聚合 请 求 的 是 示例 : 


AggregationBuilder aggregation = 
AggregationBuilders 
.geohashGrid("agg") 
.field("address.location") 
.precision(4); 


使 用 聚合 请 求 


import org.elasticsearch.search.aggregations.bucket.geogrid.GeoH 
ashGrid; 


// sr is here your SearchResponse object 
GeoHashGrid agg - sr.getAggregations().get("agg"); 


// For each entry 
for (GeoHashGrid.Bucket entry : agg.getBuckets()) { 
String keyAsString - entry.getKeyAsString(); // key as Strin 


GeoPoint key - (GeoPoint) entry.getKey(); // key as geo p 
oint 
long docCount = entry.getDocCount(); // Doc count 


logger.info("key [{}], point {}, doc count [{}]", keyAsStrin 
g, key, docCount); 


j 


输出 : 


`> key [gbqu], point [47.197265625, -1.58203125], doc count [1282] key [gbvn], 
point [50.361328125, -4.04296875], doc count [1248] key [u1j0], point 
[50.712890625, 7.20703125], doc count [1156] key [00j2], point [45.087890625, 
7.55859375], doc count [1138] ... 


Query DSL 


Elasticsearch 提供 了 一 个 基于 JSON 的 完整 的 查询 DSL 来 定义 查询 。 


Elasticsearch 以 类 似 于 REST Query DSL 的 方式 提供 完整 的 Java 查 询 ds|。 查询 构 
建 器 的 工厂 是 QueryBuilders 。 一 旦 的 查询 准备 就 绪 ， 就 可 以 使 用 Search API 


o 


要 使 用 QueryBuilder， 只 需 将 它们 导入 到 类 中 : 


import static org.elasticsearch.index.query.QueryBuilders.*; 


注意 ， 可 以 使 用 QueryBuilder 对 象 上 的 toString () 方法 打印 。 


QueryBuilder 可 以 用 于 接受 任何 查询 API， 如 count 和 search 。 


Match All Query 
最 简单 的 查询 ， 它 匹配 所 有 文档 


查看 Match All Query 


QueryBuilder qb = matchAllQuery(); 


Full text queries 全 文 搜索 


高 级 别 的 全 文 搜索 通常 用 于 在 全 文字 段 (例如 : 一 封 邮 件 的 正文 ) 上 进行 全 文 搜 
索 。 它 们 了 解 如 何 分 析 查 询 的 字段 ， 并 在 执行 之 前 将 每 个 字段 的 分 析 器 (或 搜索 分 
ME) 应 用 于 查询 字符 串 。 


这 样 的 查询 有 以 下 这 些 
e 匹配 查询 (match query) 
用 于 执行 全 文 查询 的 标准 查询 ， 包 括 模 糊 匹 配 和 词组 或 邻近 程度 的 查询 


查看 Match Query 


QueryBuilder qb = matchQuery( 
"name", //field 字段 
"kimchy elasticsearch" // text 


); 
e 多 字段 查询 (multi match query) 


可 以 用 来 对 多 个 字段 的 版 本 进行 匹配 查询 


查看 Multi Match Query 


QueryBuilder qb = multiMatchQuery( 
"kimchy elasticsearch", //text 
"user", "message" //fields 多 个 字段 


e 常用 术语 查询 (common terms query) 
可 以 对 一 些 比较 专业 的 偏 门 词 语 进行 的 更 加 专业 的 查询 


查看 Common Terms Query 


QueryBuilder qb = commonTermsQuery("name", //field 字段 
"kimchy"); // value 


e 查询 语句 查询 (query. string query) 


与 lucene 查 询 语 名 的 语法 结合 的 更 加 紧密 的 一 种 查询 ， 允 许 你 在 一 个 查询 语句 中 使 
用 多 个 特殊 条 件 关键 字 (如 : ANDIORINOT ) 对 多 个 字段 进行 查询 ， 当 然 这 种 查 
询 仅 限 专家 用 户 去 使 用 。 


查看 Query String Query 


QueryBuilder qb = queryStringQuery("+kimchy -elasticsearch"); 
//text 
e 简单 查询 语句 (simple query. string) 

是 一 种 适合 直接 暴露 给 用 户 的 简单 的 且 具 有 非常 完善 的 查询 语法 的 查询 语句 


查看 Simple Query String Query 


QueryBuilder qb = simpleQueryStringQuery("+kimchy -elasticsearch 
a //text 


Term level queries 术语 查询 


虽然 全 文 查询 将 在 执行 之 前 分 析 查 询 字 符 串 ， 但 是 项 级 别 查询 对 存储 在 反 向 索引 中 
的 确切 项 进行 操作 。 


通常 用 于 结构 化 数据 ， 如 数字 、 日 期 和 枚 举 ， 而 不 是 全 文字 段 。 或 者 ， 在 分 析 过 程 
之 前 ， 它 允许 你 绘制 低级 查询 。 


这 样 的 查询 有 以 下 这 些 : 
e Term Query (项 查询 ) 
查询 包含 在 指定 字段 中 指定 的 确切 值 的 文档 。 


查看 Term Query 


QueryBuilder qb = termQuery( 
"name", //field 
"kimchy" //text 

); 

e Terms Query (多 项 查询 ) 


查询 包含 任意 一 个 在 指定 字段 中 指定 的 多 个 确切 值 的 文档 。 


查看 Terms Query 


QueryBuilder qb = termsQuery("tags", //field 
"blue", "pill"); //values 
e Range Query (范围 查询 ) 
查询 指定 字段 包含 指定 范围 内 的 值 〈 日 期 ， 数 字 或 字符 串 ) 的 文档 。 
查看 Range Query 
方法 : 


1. gte() :范围 查询 将 匹配 字段 值 大 于 或 等 于 此 参数 值 的 文档 。 


. gt() :范围 查询 将 匹配 字段 值 大 于 此 参数 值 的 文档 。 

. Ite() :范围 查询 将 匹配 字段 值 小 于 或 等 于 此 参数 值 的 文档 。 

. lt() :范围 查询 将 匹配 字段 值 小 于 此 参数 值 的 文档 。 

. from() 开始 值 to() 结束 值 XA 432% 5 includeLower()feincludeUpper() # 4 Ae 
套 使 用 。 

6. includeLower(true) 表示 from() 查询 将 匹配 字段 值 大 于 或 等 于 此 参数 值 的 文 

Bo 

7. includeLower(false) 表示 from() 查询 将 匹配 字段 值 大 于 此 参数 值 的 文档 。 

8. includeUpper(true) 表示 to() 查询 将 匹配 字段 值 小 于 或 等 于 此 参数 值 的 文档 。 

9. includeUpper(false) 表示 to() 查询 将 匹配 字段 值 小 于 此 参数 值 的 文档 。 


a A O N 


QueryBuilder qb = rangeQuery("price") //field 


.from(5) // 74648» £jáncludeLower() 
feincludeUpper ( ) BAA 2518 FA 

.to(10) //98 RM» 5includeLower() 
feincludeUpper ( ) 42 Ec 254€ M 

.includeLower(true) // true: 表示 from() 查询 


将 匹配 字段 值 大 于 或 等 于 此 参数 值 的 文档 false: 表示 from() 查询 将 匹配 字段 
值 大 于 此 参数 值 的 文档 。 

.includeUpper(false); //true: 表 示 to() 查询 将 匹 
配 字段 值 小 于 或 等 于 此 参数 值 的 文档 ; false: 7i to() 查询 将 匹配 字段 值 小 于 此 
参数 值 的 文档 。 


实例 


// Query 

RangeQueryBuilder rangeQueryBuilder - QueryBuilders.rangeQuery(" 
age"); 

rangeQueryBuilder.from(19); 

rangeQueryBuilder.to(21); 

rangeQueryBuilder.includeLower(true); 
rangeQueryBuilder.includeUpper(true); 

//RangeQueryBuilder rangeQueryBuilder - QueryBuilders.rangeQuery 
("age").gte(19).1te(21); 

// Search 

SearchRequestBuilder searchRequestBuilder - client.prepareSearch 
(index); 

searchRequestBuilder.setTypes(type); 
searchRequestBuilder.setQuery(rangeQueryBuilder); 

// 执行 

SearchResponse searchResponse = searchRequestBuilder.execute().a 
ctionGet(); 


上 面 代 码 中 的 查询 语句 与 下 面 的 是 等 价 的 : 


QueryBuilder queryBuilder = QueryBuilders.rangeQuery("age").gte( 
19).1te(21); 


e Exists Query (存在 查询 ) 


查询 指定 的 字段 包含 任何 非 空 值 的 文档 ,如 果 指 定 字段 上 至 少 存 在 一 个 no-null 的 值 就 


= 


会 返回 该 文档 。 


查看 Exists Query 


QueryBuilder qb = existsQuery("name"); 


实例 


// Query 

ExistsQueryBuilder existsQueryBuilder - QueryBuilders.existsQuer 
y("name"); 

// Search 

SearchRequestBuilder searchRequestBuilder - client.prepareSearch 
(index); 

searchRequestBuilder.setTypes(type); 
searchRequestBuilder.setQuery(existsQueryBuilder); 

// 执行 

SearchResponse searchResponse - searchRequestBuilder.get(); 


举例 说 明 ， 下 面 的 几 个 文档 都 会 得 到 上 面 代 码 的 匹配 : 


"name": "yoona" ) 
"name" : "N } 
"name" : nm n } 


"name": ["yoona"] } 


AAAS 


"name": ["yoona", null ] } 


第 一 个 是 字符 串 ， 是 一 个 非 null 的 值 。 


$ 
| 


第 二 个 是 空 字符 串 ， 也 是 非 null。 


第 三 个 使 用 标准 分 析 器 的 情况 下 尽管 不 会 返回 词 条 ， 但 是 原始 字段 值 是 非 null 的 
(Even though the standard analyzer would emit zero tokens, the original field is 
non-null) » 


第 五 个 中 至 少 有 一 个 是 非 null 值 。 

下 面 几 个 文档 不 会 得 到 上 面 代 码 的 匹配 : 
"name": null } 

"name": [] } 


"name": [null] } 
"user": bare 


CA mS 一 一 


第 一 个 是 null 值 。 


第 二 个 没有 值 2 


第 三 个 只 有 null 值 ， 至少 需 要 一 个 非 null 值 。 

第 四 个 与 指定 字段 不 匹配 。 

e Prefix Query (前 级 查询 ) 

查找 指定 字段 包含 以 指定 的 精确 前 级 开头 的 值 的 文档 。 


查看 Prefix Query 


QueryBuilder qb = prefixQuery( 
"brand", //field 
"heine" //prefix 


); 


e Wildcard Query (通配符 查询 ) 


查询 指定 字段 包含 与 指定 模式 匹配 的 值 的 文档 ， 其 中 该 模式 支持 单字 符 通配符 
(?) 和 多 字符 通配符 (*) ,和 前 级 查询 一 样 ， 通 配 符 查询 指定 字段 是 未 分 析 的 
(not analyzed ) 
可 以 使 用 星 号 代替 0 个 或 多 个 字符 ， 使 用 问号 代替 一 个 字符 。 星 号 表示 匹配 的 数量 
不 受 限 制 ， 而 后 者 的 匹配 字符 数 则 受到 限制 。 这 个 技巧 主要 用 于 英文 搜索 中 ， 如 输 
入 “computer””， 就 可 以 找到 “computer、computers、computerised 、 
computerized” 等 单词 ， 而 输入 “comp?ter”"， 则 只 能 找到 “computer、compater、 
competer" 等 单词 。 注 意 的 是 通配符 查询 不 大 注重 性 能 ， 在 可 能 时 尽量 避免 ， 特 别 
是 要 避免 前 级 通配符 (以 通配符 开始 的 词 条 ) > 


QueryBuilder qb = wildcardQuery("user", "k?mc*"); 


实例 


// Query 

WildcardQueryBuilder wildcardQueryBuilder - QueryBuilders.wildca 
rdQuery("country"，" 西 * 牙 ")， 

// Search 

SearchRequestBuilder searchRequestBuilder = client.prepareSearch 
(index); 

searchRequestBuilder.setTypes(type); 
searchRequestBuilder.setQuery(wildcardQueryBuilder); 

// 执行 

SearchResponse searchResponse - searchRequestBuilder.get(); 


查看 Wildcard Query 
e Regexp Query (正则 表达 式 查询 ) 
查询 指定 的 字段 包含 与 指定 的 正则 表达 式 匹 配 的 值 的 文档 。 


和 前 级 查询 一 样 ， 正 则 表达 式 查 询 指 定 字 段 是 未 分 析 的 (not analyzed) 。 正 则 表 
达 式 查询 的 性 能 取决 于 所 选 的 正则 表达 式 。 如 果 我 们 的 正则 表达 式 匹 配 许多 词 条 ， 
查询 将 很 慢 。 一 般 规 则 是 ， 正 则 表达 式 匹配 的 词 条 数 越 高 ， 查 询 越 慢 。 


查看 Regexp Query 
QueryBuilder qb = regexpQuery( 


"name.first", //field 
MSc //regexp 


实例 


// Query 
RegexpQueryBuilder regexpQueryBuilder - QueryBuilders.regexpQuer 
y("country", "(®9#| 8%) f"); 


// Search 

SearchRequestBuilder searchRequestBuilder - client.prepareSearch 
(index); 

searchRequestBuilder.setTypes(type); 
searchRequestBuilder.setQuery(regexpQueryBuilder); 

// 执行 

SearchResponse searchResponse - searchRequestBuilder.get(); 


e Fuzzy Query (模糊 查询 ) 


查询 指定 字段 包含 与 指定 术语 模糊 相似 的 术语 的 文档 。 模 类 性 测量 为 1 或 2 的 
Levenshtein ° 


如 果 指 定 的 字段 是 string 类 型 ， 模 糊 查 询 是 基于 编辑 距离 算法 来 匹配 文档 。 编 辑 距 
离 的 计算 基于 我 们 提供 的 查询 词 条 和 被 搜索 文档 。 如 果 指 定 的 字段 是 数值 类 型 或 者 
日 期 类 型 ， 模 糊 查 询 基 于 在 字段 值 上 进行 加 减 操作 来 匹配 文档 (The fuzzy query 
uses similarity based on Levenshtein edit distance for string fields, and a +/- 
margin on numeric and date fields) 。 此 查询 很 占用 CPU 资 源 ， 但 当 需 要 模糊 匹配 
时 它 很 有 用 ， 例 如 ， 当 用 户 拼写 错误 时 。 另 外 我 们 可 以 在 搜索 词 的 尾部 加 上 字符 
“~” 来 进行 模糊 查询 。 


查看 Fuzzy Query 


QueryBuilder qb = fuzzyQuery( 
"name", //field 
"kimzhy" //text 

); 


e Type Query (类 型 查询 ) 
查询 指定 类 型 的 文档 。 


查看 Type Query 


QueryBuilder qb - typeQuery("my type"); //type 


e Ids Query (ID 查询 ) 
查询 具有 指定 类 型 和 |D 的 文档 。 


查看 lds Query 


QueryBuilder qb = idsQuery("my type", "type2") 
.addIds("1", "4", "100"); 


QueryBuilder qb = idsQuery() // type 是 可 选择 的 ， 可 以 不 写 
addrds ("1 uan T100"); 


Compound queries 


复合 查询 用 来 包装 其 他 复合 或 者 叶子 查询 ， 一 方面 可 综合 其 结果 和 分 数 ， 从 而 改变 
它 的 行为 ， 另 一 方面 可 从 查询 切换 到 过 滤器 上 下 文 。 此 类 查询 包含 : 


e constant score 查询 


这 是 一 个 包装 其 他 查询 的 查询 ， 并 且 在 过 滤器 上 下 文中 执行 。 与 此 查询 匹配 的 所 有 
文件 都 需要 返回 相同 的 “常量 ” score © 


查看 Constant Score Query 


QueryBuilder qb = constantScoreQuery( 
termQuery("name", "kimchy") // 519184 


) 
.boost(2.0f);  //7% 


e bool 查询 


组 合 多 个 叶子 并 发 查询 或 复合 查询 条 件 的 默认 查询 类 型 ， 例 如 must, should, 
must not, 以 及 filter 条 件 。 Æ must 和 should 子 句 他 们 的 分 数 相 结合 -匹配 条 件 越 
多 ， 预 期 越 好 -而 must not 和 filter 子 句 在 过 滤器 上 下 文中 执行 。 


查看 Bool Query 


QueryBuilder qb = boolQuery() 
.must(termQuery("content", "test1")) //must query 
.must(termQuery("content", "test4")) 
.mustNot(termQuery("content", "test2")) //must not query 
.should(termQuery("content", "test3")) // should query 
.filter(termQuery("content", "test5// 与 一 般 查 询 作用 一 样 ， 只 不 过 
不 参与 评分 


e dis max 查询 
支持 多 并 发 查询 的 查询 ， 并 可 返回 与 任意 查询 条 件 子 名 匹配 的 任何 文档 类 型 。 与 


bool 查询 可 以 将 所 有 匹配 查询 的 分 数 相 结合 使 用 的 方式 不 同 的 是 ，dis_max 查询 只 
使 用 最 佳 匹 配 查询 条 件 的 分 数 。 


查看 Dis Max Query 


QueryBuilder qb - disMaxQuery() 
.add(termQuery("name", "kimchy")) 
.add(termQuery("name", "elasticsearch")) 
.boost(1.2f) //boost factor 
.tieBreaker(0.7f); //tie breaker 


e function score 查询 


使 用 函数 修改 主 查 询 返 回 的 分 数 ， 以 考虑 诸如 流行 度 ， 新 近 度 ， 距 离 或 使 用 脚本 实 
现 的 自 定义 算法 等 因素 。 


查看 Function Score Query 


import static org.elasticsearch.index.query.functionscore.ScoreF 
unctionBuilders.*; 


FilterFunctionBuilder[] functions - ( 
new FunctionScoreQueryBuilder.FilterFunctionBuilder( 


matchQuery("name", "kimchy"), // 
根据 查询 添加 第 一 个 function 
randomFunction("ABCDEF")), // 


根据 给 定 的 种 子 随机 分 数 
new FunctionScoreQueryBuilder.FilterFunctionBuilder( 
exponentialDecayFunction("age", OL, 1L)) // 
根据 年 龄 字段 添加 另 一 个 function 


J; 
QueryBuilder qb = QueryBuilders.functionScoreQuery(functions); 
e boosting 查询 


返回 匹配 positive 查询 的 文档 ， 并 且 当 减少 文档 的 分 数 时 其 结果 也 匹配 negative 查 
询 。 


查看 Boosting Query 


QueryBuilder qb - boostingQuery( 
termQuery ("name", "kimchy"), 
termQuery("name", "dadoonet")) 

.hegativeBoost(0.2f); 


e indices 查询 
对 指定 的 索引 执行 一 个 查询 ， 对 其 他 索引 执行 另 一 个 查询 。 
查看 Indices Query 


在 5.0.0 中 已 弃 用 。 用 搜索 index 字段 来 代替 


// Using another query when no match for the main one 
QueryBuilder qb - indicesQuery( 
termQuery("tag", "wow"), 
"index1", "index2" 
).noMatchQuery(termQuery("tag", "kow")); 


// Using all (match all) or none (match no documents) 
QueryBuilder qb - indicesQuery( 
termQuery("tag", "wow"), 
"index1", "index2" 
).noMatchQuery("all"); 


Joining queries 


4& 1$. ElasticSearch 这 样 的 分 布 式 系统 中 执行 全 SQL 风格 的 连接 查询 代价 昂贵 ， 是 
不 可 行 的 。 相 应 地 ， 为 了 实现 水 平 规模 地 扩展 ，ElasticSearch 提供 了 两 种 形式 的 
join ° 

e nested query (4X & & i$) 


SAP TE 6,8 t AAA? GRE BUR GR RI RMR > EA RAT 
AE 29 — Ah 3p RRA UTI EE AT) 


4 Nested Query 


QueryBuilder qb - nestedQuery( 
"obj1", //nested ÉSA xe 
boolQuery() // 查询 查询 中 引用 的 任何 字段 都 
必须 使 用 完整 路 径 (fully qualified) 。 
.must(matchQuery("obji.name", "blue")) 
.must(rangeQuery("obj1.count").gt(5)), 
ScoreMode.Avg // score 模型 ScoreMode.Max 
, ScoreMode.Min, ScoreMode.Total, ScoreMode.Avg or ScoreMode.Non 
e 


); 


e has child (4 + & iy) and has. parent (4 % #74) queries 
一 类 父子 关系 可 以 存在 单个 的 索引 的 两 个 类 型 的 文档 之 间 。has child 查询 将 返回 
其 子 文档 能 满足 特定 的 查询 的 父 文档 ， 而 has parent 则 返回 其 父 文档 能 满足 特定 
查询 的 子 文档 
Has Child Query 
查看 Has Child Query 


使 用 has child 查询 时 ， 必 须 使 用 PreBuiltTransportClient 而 不 是 常规 
Client ， 这 个 点 很 重要 : 


Settings settings - Settings.builder().put("cluster.name", "elas 
ticsearch").build(); 

TransportClient client - new PreBuiltTransportClient(settings); 
client.addTransportAddress(new InetSocketTransportAddress(new In 
etSocketAddress(InetAddresses.forString("127.0.0.1"), 9300))); 


否则 ， parent-join 模块 不 会 被 加 载 ， 并 且 不 能 从 transport client 使 
用 has child 查询 。 


QueryBuilder qb = JoinQueryBuilders.hasChildQuery( 


"blog_tag", // 要 查询 的 子 类 型 
termQuery("tag","something"), // 查 询 
ScoreMode.Avg //score 模型 ScoreMode.Avg, S 


coreMode.Max, ScoreMode.Min, ScoreMode.None or ScoreMode. Total 


): 


Has Parent Query 
查看 Has Parent 


使 用 has parent 查询 时 ， 必 须 使 用 PreBuiltTransportClient 而 不 是 常规 
Client ， 这 个 点 很 重要 : 


Settings settings = Settings.builder().put("cluster.name", "elas 
ticsearch").build(); 

TransportClient client - new PreBuiltTransportClient(settings); 
client.addTransportAddress(new InetSocketTransportAddress(new In 
etSocketAddress(InetAddresses.forString("127.0.0.1"), 9300))); 


否则 ， parent-join 模块 不 会 被 加 载 ， 并 且 不 能 从 transport client 使 
用 has child 查询 。 


QueryBuilder qb - JoinQueryBuilders.hasParentQuery( 


"blog", // 要 查询 的 子 类 型 
termQuery("tag"," something"), // 查 询 
false // 是 否 从 父 hit 的 Score HAF hit 


); 


参考 term 查询 中 的 terms-lookup mechanism ， 它 允许 你 在 另 一 个 文档 的 值 中 创建 


一 个 term 查询 。 


Geo queries 地 理 位 置 查询 


Elasticsearch 支 持 两 种 类 型 的 地 理 数据 : geo_point 类 型 支持 成 对 的 纬度 /经 度 ， 
geo_shape 类 型 支持 点 、 线 、 圆 、 多 边 形 、 多 个 多 边 形 等 。 在 这 组 的 查询 中 : 


e geo shape & i9] 
查找 要 么 相交 ， 包 人 钨 的 ， 要 么 指定 形状 不 相交 的 地 理 形 状 的 文档 。 
查看 Geo Shape Query 


geo shape 类 型 使 用 spatialaJ 和 JTS ， 这 两 者 都 是 可 选 的 依赖 项 。 
因此 ， 人 必须 将 Spatial4] 和 JTS 添加 到 classpath 中 才能 使 用 此 类 


Jn] 。 
"Ee 


«dependency» 
«groupId»org.locationtech.spatial4j«/groupId» 
<artifactId>spatial4j</artifactId> 
<version>0.6</version> 

</dependency> 


<dependency> 
<groupId>com.vividsolutions</groupId> 
<artifactId>jts</artifactld> 
<version>1.13</version> 
<exclusions> 
<exclusion> 
<groupId>xerces</grouplId> 
<artifactId>xercesImpl</artifactId> 
</exclusion> 
</exclusions> 
</dependency> 


// Import ShapeRelation and ShapeBuilder 
import org.elasticsearch.common.geo.ShapeRelation; 
import org.elasticsearch.common.geo.builders.ShapeBuilder; 


List<Coordinate> points = new ArrayList<>(); 
points.add(new Coordinate(0, 0)); 
points.add(new Coordinate(0, 10)); 
points.add(new Coordinate(10, 10)); 
points.add(new Coordinate(10, 0)); 
points.add(new Coordinate(0, 0)); 


QueryBuilder qb - geoShapeQuery( 


"pin.location", //field 
ShapeBuilders.newMultiPoint(points) //shape 
.relation(ShapeRelation.WITHIN); //relation 可 以 是 


ShapeRelation.CONTAINS, ShapeRelation.WITHIN, ShapeRelation.INT 
ERSECTS X ShapeRelation.DISJOINT 


// Using pre-indexed shapes 
QueryBuilder qb - geoShapeQuery( 


"pin.location", //field 

"DEU", //The ID of the documen 
t that containing the pre-indexed shape. 

"countries") //Index type where the 


pre-indexed shape is. 
.relation(ShapeRelation.WITHIN)) //relation 
.indexedShapeIndex("shapes") //Name of the index whe 
re the pre-indexed shape is. Defaults to shapes. 
.indexedShapePath("location"); //The field specified a 
s path containing the pre-indexed shape. Defaults to shape. 


e geo bounding box 查询 
查找 落 入 指定 的 矩形 地 理 点 的 文档 。 


查看 Geo Bounding Box Query 


QueryBuilder qb = geoBoundingBoxQuery("pin.location") //field 


.setCorners(40.73, -74.1, / /bounding 
box top left point 
40.717, -73.99); / /bounding 


box bottom right point 


e geo distance 查询 
查找 在 一 个 中 心 点 指定 范围 内 的 地 理 点 文档 。 


查看 Geo Distance Query 


QueryBuilder qb = geoDistanceQuery("pin.location") 
.point(40, -70) 

nt 
.distance(200, DistanceUnit.KILOMETERS); 

rom center point 


e geo polygon 查询 
查找 指定 多 边 形 内 地 理 点 的 文档 。 


查看 Geo Polygon Query 


List«GeoPoint» points = new ArrayList<>(); 

r polygon of points a document should fall within 
points.add(new GeoPoint(40, -70)); 

points.add(new GeoPoint(30, -80)); 

points.add(new GeoPoint(20, -90)); 


QueryBuilder qb - 
geoPolygonQuery("pin.location", points); 
ise the query with field and points 


//field 
//center poi 


//distance f 


//add you 


//initial 


Specialized queries 
e more like this query( 相 似 度 查询 ) 
这 个 查询 能 检索 到 与 指定 文本 、 文 档 或 者 文档 集合 相似 的 文档 。 
查看 More Like This Query 
String[] fields = {"name.first", "name.last"}; 
/fields 
String[] texts = ("text like this one"); 


/text 
Item[] items - null; 


QueryBuilder qb = moreLikeThisQuery(fields, texts, items) 
.minTermFreq(1) 

/ignore threshold 
.maxQueryTerms(12); 

/max num of Terms in generated queries 


e Script query 
该 查询 允许 脚本 充当 过 滤器 。 另 请 参阅 function. score query ° 


查看 Script Query 


QueryBuilder qb = scriptQuery( 
new Script("doc['num1'].value > 1") //inlined script 


): 


如 果 已 经 在 每 个 数据 节点 上 存储 名 为 “myscript.painless 的 脚本 ， 请 执行 以 下 操 
作 : 


doc['num1'].value > params ,param1 


然后 使 用 : 


QueryBuilder qb - scriptQuery( 
new Script( 


ScriptType.FILE, // 脚 本 类 型 ScriptT 
ype.FILE, ScriptType.INLINE* ScriptType.INDEXED 
"painless", //Scripting engin 
e 脚本 引擎 
"myscript", //Script name 脚本 


名 


Collections.singletonMap("param1", 5)) //Parameters as a 
Map of «String, Object» 


); 


e Percolate Query 


查看 Percolate Query 


Settings settings = Settings.builder().put("cluster.name", "elas 
ticsearch").build(); 

TransportClient client - new PreBuiltTransportClient(settings); 
client.addTransportAddress(new InetSocketTransportAddress(new In 
etSocketAddress(InetAddresses.forString("127.0.0.1"), 9300))); 


在 可 以 使 用 percolate 查询 之 前 ， 应 该 添加 percolator 映射 ， 并 且 应 该 对 包 
4 percolator 查询 的 文档 建立 索引 : 


// create an index with a percolator field with the name 'query' 


client.admin().indices().prepareCreate("myIndexName" ) 

.addMapping("query", "query", "type=perc 
olator") 

.addMapping("docs", "content", "type-tex 
t^) 

.get(); 


//This is the query we're registering in the percolator 
QueryBuilder qb - termQuery("content", "amazing"); 


//Index the query - register it in the percolator 
client.prepareIndex("myIndexName", "query", "myDesignatedQueryNa 
me") 
.setSource(jsonBuilder() 
.startObject() 
.field("query", qb) // Register the query 
.endObject()) 
.setRefreshPolicy(RefreshPolicy.IMMEDIATE) // Needed when th 
e query shall be available immediately 


get ( ); 


在 上 面 的 index 中 query 名 为 myDesignatedQueryName 


为 了 检查 文档 注册 查询 ,使 用 这 个 代码 : 


//Build a document to check against the percolator 
XContentBuilder docBuilder - XContentFactory.jsonBuilder().start 
Object(); 

docBuilder.field("content", "This is amazing!"); 
docBuilder.endObject(); //End of the JSON root object 


PercolateQueryBuilder percolateQuery - new PercolateQueryBuilder 
("query", "docs", docBuilder.bytes()); 


// Percolate, by executing the percolator query in the query dsl 


SearchResponse response - client().prepareSearch("myIndexName") 
.setQuery(percolateQuery)) 
.get(); 
//Iterate over the results 
for(SearchHit hit : response.getHits()) { 
// Percolator queries as hit 


Span queries 

e span term & i5 
等 同 于 term query ， 但 与 其 他 Span 查 询 一 起 使 用 。 
查看 Span Term Query 

QueryBuilder qb = spanTermQuery( 


"user", //field 
"kimchy" //value 


); 


e span multi & 35 
包含 term, range, prefix, wildcard, regexp 或 者 fuzzy 查询 。 
查看 Span Multi Term Query 
QueryBuilder qb = spanMultiTermQueryBuilder( 
prefixQuery("user", "ki") //* vA MultiTerm 


QueryBuilder 的 扩展 Hite : FuzzyQueryBuilder, PrefixQueryBuilder, 
RangeQueryBuilder, RegexpQueryBuilder > WildcardQueryBuilder ° 


); 
e span first & i9 


接受 另 一 个 Span 查 询 ， 其 匹配 必须 出 现在 字段 的 前 N 个 位 置 。 


查看 Span First Query 


QueryBuilder qb = spanFirstQuery( 

spanTermQuery("user", "kimchy"), //query 

3 //max end positi 
on 


); 


e span near & i$ 


接受 多 个 Span 查 询 ， 其 匹配 必须 在 彼此 的 指定 距离 内 ， 并 且 可 能 顺序 相同 。 


查看 Span Near Query 


QueryBuilder qb = spanNearQuery( 

spanTermQuery("field","value1"), //span term quer 
ies 

12) //slop factor: t 
he maximum number of intervening unmatched positions 

.addClause(spanTermQuery("field","value2")) //span term quer 
ies 

.addClause(spanTermQuery("field","value3")) //span term quer 
les 

.inOrder(false); //whether matche 
s are required to be in-order 


e Span_or 查 询 
组 合 多 个 Span 查 询 - 返回 与 任何 指定 查询 匹配 的 文档 。 


查看 Span Or Query 


QueryBuilder qb = spanOrQuery( 
spanTermQuery("field","value1")) 
.addClause(spanTermQuery("field", "value2") ) 
.addClause(spanTermQuery("field", "value3")); //span term q 
ueries 


e span_not#74q 
包装 另 一 个 Span 查 询 ， 并 排除 与 该 查询 匹配 的 所 有 文档 。 
查 


看 Span Not Query 


QueryBuilder qb = spanNotQuery( 

spanTermQuery("field","value1"), //span query whose matche 
s are filtered 

spanTermQuery("field","value2")); //span query whose matche 
s must not overlap those returned 


e span containing 查询 
接受 Span 查 询 的 列表 ， 但 仅 返 回 与 第 二 个 Spans 查 询 匹 配 的 Span。 


查看 Span Containing Query 


QueryBuilder qb = spanContainingQuery( 
spanNearQuery(spanTermQuery("field1","bar"), 5) //big part 
.addClause(spanTermQuery("field1","baz")) 
.inOrder(true), 
spanTermQuery ( "field1","foo")); //little par 


e span within $19] 


只 要 其 span 位 于 由 其 他 Span 查 询 列表 返回 的 范围 内 ， 就 会 返回 单个 Span 查 询 的 结 
果 ， 


查看 Span Within Query 


QueryBuilder qb = spanwithinQuery( 
spanNearQuery(spanTermQuery("field1", "bar"), 5) //big part 
.addClause(spanTermQuery("fieldi", "baz")) 
.inOrder(true), 
spanTermQuery("fieldi", "foo")); //little p 
art 
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